xml api что это

Java XML API: выбираем правильно. StAX: работаем с удовольствием

в 60% проектов и посвятил ей занятие своей стажировки Masterjava. Наиболее частые его применения: XHTML, SOAP, различные конфигурации (например Tomcat, SoapUI, IntelliJ IDEA, Spring XML конфигурация), импорт-экспорт данных.

В Java есть несколько API для работы с XML и для разработчика важно понимать, какое из API требуется выбрать в каждой конкретной ситуации. В этой статье я кратко перечислю все Java XML API, их назначение и примеры использования, и подробнее остановлюсь на работе с достаточно редкой, но в ряде случаев единственно верной технологией StAX. Предполагается что с элементами XML вы уже знакомы.

Java XML API: выбираем правильно

StAX: работаем с удовольствием

Прежде всего хочу отметить, что со StAX можно работать через 2 API: низкоуровневое XMLStreamReader, возвращающая примитивы и высокоуровневое XMLEventReader, которое возвращает объекты и расходует больше памяти. Далее я буду работать с XMLStreamReader. Сделав над ним обертку работа с XML будет простой и удобной.Разберем небольшой пример: есть простой XML с городами и юзерами:В реальности этот XML может содержать сотни городов и сотни тысяч / миллионы юзеров. Все, что требуется: распечатать список городов. В данном случае StAX API — единственно верный выбор. Добавляем в проект вспомогательный класс StaxStreamProcessor :Далее мы последовательно идем по XML, считываем все интересные нам события и выводим требуемую информацию:Чтобы постоянно не дублировать в программе часто повторяющийся код поиска нужного события в XML, мы можем добавить его в StaxStreamProcessor :Пользоваться утильным классом станет не просто, а очень просто:Недостаток этого кода — мы совершенно бесполезно потратим ресурсы на прохождение по сотням тысяч ненужных нам юзеров вместо завершения программы. Нужно добавить условие прекращение сканирования XML. Обычно это конец тэга родительского элемента (в нашем случае Cities ). Добавляем в StaxStreamProcessor еще один утильный метод, который сканирует XML либо до конца тэга родителя, либо до заданного элемента:Добавим методы чтения атрибута и текста:Код вызова останется суперпростым и мы прекратим обработку XML сразу после конца тега Cities :StAX API требует аккуратность при чтении событий. Если в выводе мы помяняем местами чтение атрибута и текста, но код станет нерабочим: после прочтения из XML названия города атрибут останется позади и будет недоступен. Также следует помнить, что, в зависимости от текущего положения XML, нам доступны одни методы API чтения из XML и недоступны другие.Используя startElement можно добираться до элементов XML любой степени вложенности и, по мере необходимости, дополнять StaxStreamProcessor другими утильными методами. Надеюсь что с данным подходом работа с StAX покажется вам легкой и удобной.

Источник

XML API¶

Обзор¶

Документация включает описание API для отправки SMS-сообщений через платформу Devino Telecom с примерами запросов. API включает в себя возможность как транзакционных, так и массовых рассылок, получение подробной статистики по рассылкам. Документ предназначен для разработчиков, которые хотят добавить возможность взаимодействия с Сервисом отправки SMS-сообщений на страницы своих сайтов или в свои приложения. Общение с сервисом осуществляется при помощи отправки XML запросов в кодировке UTF-8 на заданный адрес сервиса по протоколу HTTPS методом POST, проверка типа контента не осуществляется. Каждый запрос может состоять из отправляемых сообщений и (или) запросов для получения статусов и (или) запросов для получения входящих сообщений. Авторизация пользователя происходит путем передачи учетных сведений в теге package, обязательна при выполнении любых запросов.

Сервис доступен по адресу:

Отправка сообщений¶

Отправка сообщений осуществляется в соответствии с очередностью по получению сообщений и временем отправки.

Параметр	Тип данных	Обязательный	Описание
Default	Нет	Тег, в котором определяются общие атрибуты, указываемые для всех отправляемых сообщений. Если какой-либо атрибут указан в сообщении, то атрибут данного тега игнорируется
msg	да	Тег сообщения, в качестве параметра указывается текст отправляемого сообщения
id	integer	Нет	Пользовательский числовой идентификатор сообщения
recipient	varchar(21)	Да	Номер телефона. Пример: 79031234567, +79031234567
sender	varchar(11)	Да	Адрес отправителя
date_beg	datetime, ISO8601	Нет	Дата отправки сообщения, указывается для отложенной отправки сообщений.
date_end	datetime, ISO8601	Нет	Дата, после которой сообщение теряет актуальность и если оно еще не было отправлено абоненту, отправляться не будет.
url	varchar(100)	Да *	Ссылка для создания wap-push сообщения
type	integer	Да	Тип сообщения: 0-обычное сообщение 1-flash сообщение 2-wap-push сообщение

На полученный запрос сервис возвращает в виде параметра статус сообщения, а в атрибутах идентификаторы, присвоенные сообщениям.

Параметр	Тип данных	Описание
msg	Тег сообщения, в качестве параметра возвращается код статуса
id	integer	Пользовательский числовой идентификатор сообщения, необязательный атрибут, возвращается при указании данного атрибута в запросе
sms_id	integer	Числовой идентификатор сообщения, присвоенный шлюзом
sms_count	integer	Реальное количество SMS к отправке

Запрос статусов сообщений¶

Статусы сообщений содержат информацию о текущем состоянии сообщения, регулярно обновляются и могут быть запрошены пользователем в любое время. Статусы можно запрашивать за последние 3 календарных дня. Максимальное количество ID в запросе 1000.

Параметр	Тип данных	Обязательный	Описание
msg	Нет	Тег сообщения, для которого происходит запрос статуса
id	integer	Нет *	Пользовательский числовой идентификатор сообщения, возвращается при указании данного атрибута в запросе
sms_id	integer	Да *	Числовой идентификатор сообщения, присвоенный шлюзом

* Можно указать любой из этих параметров

В ответ на запрос возвращается XML документ содержащий статусы для запрошенных сообщений, либо соответствующие коды ошибок.

Параметр	Тип данных	Описание
msg	Тег сообщения, для которого происходит запрос статуса, в качестве параметра возвращается код статуса
id	integer	Пользовательский числовой идентификатор сообщения, возвращается при указании данного атрибута в запросе
sms_id	integer	Числовой идентификатор сообщения, присвоенный шлюзом
sms_count	integer	Реальное количество SMS к отправке
date_completed	datetime, ISO8601	Дата присвоения финального статуса

Коды статусов документа¶

При отправке XML документа могут возвращаться следующие коды ошибок:

Код	HTTP Status	Расшифровка
ERR_UNKNOWN	200	Неизвестная ошибка
ERR_FORMAT	201	Неправильный формат документа
ERR_AUTHORIZATION	202	Ошибка авторизации

Коды статусов сообщений

Данные коды используются при возврате статусов сообщений.

Источник

Понимание XML

Узнайте, как Расширяемый язык разметки (Extensible Markup Language — XML) облегчает универсальный доступ к данным. XML — основанный на Unicode метаязык: язык для описания языков разметки. Он не привязан ни к одному языку программирования, операционной системе или поставщику программного обеспечения. XML обеспечивает доступ к огромному количеству технологий по манипулированию, структурированию, трансформированию и запрашиванию данных.

Введение

Расширяемый язык разметки (XML) изначально был задуман как язык для описания новых форматов документов World Wide Web. XML происходит от Стандартного обобщенного языка разметки (Standard Generalized Markup Language — SGML) и может считаться метаязыком: языком для определения языков разметки. SGML и XML — это ориентированные на текст форматы, которые обеспечивают механизмы описания структур документов с помощью тэгов разметки (слов, взятых в угловые скобки ‘ ’ ). Web-разработчики могут заметить некоторую схожесть между HTML и XML, обусловленную тем фактом, что они оба происходят от SGML.

Поскольку применение XML возросло, сейчас общепринято считать, что XML полезен не только при описании новых форматов документов для Web, но также подходит для описания структурированных данных. Примеры структурированных данных включают информацию, которая обычно содержится в крупноформатных таблицах, файлах конфигурации программы и сетевых протоколах.

XML является предпочтительным для существовавших ранее форматов данных, потому что XML может запросто представить и табличные данные (такие как реляционные данные из базы данных или больших таблиц), и псевдоструктурированные данные (такие как Web-страницы или деловые документы). Популярные ранние форматы, такие как файлы с разделяемыми запятой значениями (CSV), или подходят для табличных данных и плохо описывают псевдоструктурированные данные, или, как RTF, слишком специализированы для псевдоструктурированных текстовых документов. Это привело к широкому распространению XML как языка для обмена информацией.

XML везде

Кроме способности представлять и структурированные, и псевдоструктурированные данные, XML имеет несколько характеристик, которые обусловили его широкое использование в качестве формата представления данных. XML — расширяемый, плотформо-независимый и поддерживает локализацию, т.к. полностью совместим с Unicode. Тот факт, что XML — текстовый формат, означает, что при возникновении необходимости XML-документы можно читать и редактировать, используя стандартные инструменты редактирования текстов.

XML не привязан ни к одному языку программирования, операционной системе или поставщику программного обеспечения. Кстати, создавать или потреблять XML, используя различные языки программирования — слишком прямолинейно. Независимость от платформ делает XML очень полезным в качестве средства достижения возможности взаимодействовать между различными платформами программирования и операционными системами.

Синтаксис XML 1.0

Как было упомянуто ранее, рекомендация W3C XML 1.0 описывает текстовый формат для описания структурированных и псевдоструктурированных данных, используя синтаксис, подобный HTML.

Сравнение XML и HTML

И HTML, и XML документы состоят из элементов, каждый из которых включает «начальный тэг» ( ), «конечный тэг» ( ) и информацию, заключенную между этими двумя тэгами (которая называется содержимым элемента). Элементы могут быть аннотированы атрибутами, содержащими метаданные об элементе и его содержимом.

Однако между HTML и XML есть существенные отличия. XML чувствителен к регистру, в то время как HTML — нет. Это значит, что в XML начальные тэги

и

различны, тогда как в HTML — это одно и то же. Другое различие между HTML и XML в том, что XML представляет концепцию правильного построения. Правила построения XML устраняют некоторую неопределенность, присущую обработке таких языков разметки как HTML, вводя такие постулаты, как то, что все значения атрибутов должны быть заключены в кавычки, и что у всех элементов должны быть или начальный и конечный тэги, или явное указание того, что это пустые элементы. Краткое описание правил построения дается в XML FAQ в разделе D.2.

Самое существенное различие между HTML и XML в том, что в HTML есть предопределенные элементы и атрибуты, поведение которых предопределено, в то время как в XML такого нет. Вместо этого, авторы документа могут создавать собственные XML-словари, предназначенные именно для их приложения или деловых нужд. В настоящее время существуют XML-словари для огромного количества отраслей промышленности и приложений: от финансовых картотек (XBRL) и финансовых операций (FpML) до Web-документов (XHTML) и сетевых протоколов (SOAP). Отсутствие предопределенных элементов и атрибутов, которые определяют, как формируется или отображается XML-документ, дает возможность авторам сосредоточиться на создании документов, которые содержат только существенную семантическую информацию в их конкретной предметной области. Отделение содержимого от представления, ставшее возможным с XML-словарями, существенно увеличивает возможности повторного использования информации и перенацеливания содержимого.

Анатомия XML-документа

Ниже приведен пример XML-документа, который представляет заказ покупателя в магазине музыкальных CD. На что надо обратить внимание — это то, как просто документ представляет и строго структурированные данные, которые описывают информацию о компакт дисках, и псевдоструктурированные данные, содержащие специальные инструкции и комментарии по определенному покупателю.

Документ начинается с необязательного описания XML, в котором указывается, какая версия XML и кодирование символом используются. Далее следует инструкция обработки xml-stylesheet, которая используется для связывания таблицы стилей, содержащей инструкции по форматированию, с XML-документом. Таблица стилей используется для формирования привлекательного внешнего вида документа в пользовательских приложениях, таких как Web-браузеры. Инструкции обработки обычно используются для введения информации о приложении в XML-документ. Например, большинство приложений, обрабатывающих содержимое приведенного выше документа, вероятно, проигнорируют инструкцию обработки xml-stylesheet. С другой стороны, приложения, используемые для отображения XML-документа, такие как Web-браузер, могли бы использовать информацию инструкции обработки для того, чтобы определить, где располагается таблица стилей, содержащая специальные инструкции для отображения документа.

Unicode + угловые скобки = возможность взаимодействовать

Сочетание тех фактов, что синтаксис XML 1.0 — текстовый и слишком простой для синтаксического разбора, привело к использованию XML как нового формата обмена данными в случаях, когда требуется возможность межплатформенного взаимодействия. Широкая доступность синтаксических анализаторов XML для большинства популярных операционных систем упрощает для неравноправных сторон на разных платформах стандартизацию XML как формата преобразования в случае необходимости совместного использования информации.

То, что XML основан на Unicode, делает его подходящим для совместного использования информации через глобальные сети, такие как World Wide Web.

Infoset и семейство XML-технологий

Хотя возможность взаимодействовать и расширяемость платформ, получаемые при использовании текстового синтаксиса XML, и являются прекрасным примером выгоды от применения XML как формата представления данных, это всего лишь одно из преимуществ, которые XML предоставляет разработчикам приложений. Другое важное преимущество от использования XML — он предоставляет единый подход к множеству технологий по манипулированию, структурированию, преобразованию и запрашиванию данных.

Информационное множество (Infoset) XML

Рекомендация информационного множества W3C XML (W3C XML Information Set recommendation) описывает абстрактное представление XML-документа. XML Infoset, главным образом, изначально выступает в роли набора определений, используемых XML-технологиями для формального описания того, с какими частями XML-документа они работают. В терминах XML Infoset описаны несколько W3C XML-технологий, включая SOAP 1.2, XML Schema и XQuery.

XML Infoset — древовидное иерархическое представление XML-документа. Информационное множество XML-документа состоит из ряда единиц информации, которые являются абстрактным представлением компонентов XML-документа. Существуют единицы информации, представляющие документ, его элементы, атрибуты, инструкции обработки, комментарии, символы, нотации, пространства имен, неразбираемые синтаксическим анализатором сущности, неразвернутые ссылки на сущности и объявление типа документа. XML Infoset — официальная попытка определить то, что должно считаться важной информацией в XML-документе. Например, Infoset не делает различий между двумя формами пустого элемента. Таким образом, следующее

согласно XML Infoset, считается эквивалентным. Аналогично, не имеет значения и тип кавычек, используемых для атрибутов; таким образом, элементы

согласно XML Infoset, эквивалентны. Список аспектов синтаксиса XML 1.0, которые не рассматриваются XML Infoset, приведен в Приложении D рекомендации Информационного множества W3C XML.

Языки Схемы

Язык XML-схемы используется для описания структуры и содержимого XML-документа. Например, схема может использоваться для определения документа, состоящего из одного или более элементов compact-disc, каждый из которых включает в качестве дочерних элементы price, title и artist. Во время обмена документами XML-схема описывает контракт между производителем и потребителем XML, поскольку она описывает то, что составляет действительное XML-сообщение передаваемое между двумя сторонами. Хотя для XML существует несколько языков схемы, от DTD до XDR, ведущим является Язык описания XML-схемы W3C (W3C XML Schema Definition Language), сокращенно XSD.

XSD уникален среди языков XML-схемы, потому что он первым пытается вывести роль XML-схемы за рамки традиционного ее применения для описания контракта между двумя сущностями, обменивающимися документами. XSD представляет концепцию Post Schema Validation Infoset (PSVI). Совместимый XSD-обработчик принимает XML Infoset как входные данные и после проверки преобразовывает его в Информационное множества после проверки схемы (PSVI). PSVI — это исходные входные данные XML Infoset с добавленными к существующим новыми единицами информации и новыми свойствами. В Рекомендации XML-схема W3C приведен список дополнений в Информационное множества после проверки схемы (PSVI).

Ниже показан пример фрагмента схемы, который описывает элемент items документа-образца, приведенного в разделе Анатомия XML-документа.

API, использующие модель дерева
Древовидная модель API представляет XML-документ как дерево узлов, которые обычно загружаются в память все сразу. Самая популярная древовидная модель API для XML — Объектная модель документа W3C (W3C Document Object Model — DOM). DOM обеспечивает возможность программно читать, манипулировать и изменять XML-документ.

Курсорные APIs

Потоковые API

Потоковые API для обработки XML позволяет обрабатывать XML-документ, сохраняя в памяти только содержимое обрабатываемого в данный момент узла. Такие API делают возможной обработку больших XML-файлов без использования слишком больших объемов памяти. Существует два основных класса потоковых API для обработки XML: передающие XML-анализаторы и принимающие XML-анализаторы.

XML-запрос

XML-преобразование

Часто надо преобразовать XML-документы из одного словаря в другой. Иногда так можно сгенерировать их в готовом для печати формате или в Web-браузере; также с помощью преобразования можно превратить документы, полученные извне, в более привычный формат.

XSLT (http://www.w3.org/TR/xslt) — первый язык XML-преобразования. Преобразование, выраженное в XSLT, описывает правила преобразования исходного дерева в результирующее дерево. Преобразование достигается путем ассоциирования шаблонов. Шаблон — это выражение XPath, может рассматриваться как регулярное выражение, ставящее части исходного дерева XML в соответствие частям строки. Шаблон ставится в соответствие элементам исходного дерева. В случаях совпадения создается экземпляр шаблона для создания части результирующего дерева. При создании результирующего дерева элементы исходного дерева могут быть отфильтрованы и реорганизованы, а произвольная структура может быть добавлена.

Следующая таблица стилей XSLT преобразовывает элемент items в Web-страницу XHTML, содержащую таблицу с информацией о компакт дисках.

XHTML-документ, созданный с использованием этой таблицы стилей, показан ниже:

Заключение

XML — это больше, чем просто текстовый формат для описания документов. Это механизм для описания структурированных и псевдоструктурированных данных, который обеспечивает доступ к богатому семейству технологий обработки таких данных. Мощные абстракции, такие как Информационное множество XML, открывают двери к обработке нетекстовых данных, таких как файловые системы, реестр Windows®, реляционные базы данных и даже объекты языков программирования, с помощью XML-технологий. XML еще на один шаг приблизил нас к универсальному доступу к данным.

Источник

Xml api что это

Универсальный модуль «Интеграции API XML» Системы позволяем проводить обмен данными в формате XML между Системой и любым сторонним приложением.

В частности с помощью данного модуля происходит обмен данными с мобильными приложениями РосБизнесСофт (iPhone, Android), c сайтами, интернет-магазинами, АТС, биллингом и т.д.

Для того, чтобы пользователь имел доступ по API, в т.ч. для подключения через мобильное приложение, ему нужно поставить соответствующую галочку в Настройках.

При помощи API интерфейса можно проводить следующие операции с данными (Объектами Системы):

У вас есть три возможности отправить XML запрос в систему:

Структура представления данных (архитектура) доступна в «Конфигураторе» (/configurator) CRM системы.

Для работы с API можно использовать вспомогательный класс на PHP. См. подробное описание класса ниже.

Общий синтаксис

Также можно передать в качестве атрибута тега параметр uid, несущий в себе уникальный идентификатор запроса. В это случае, при ответе системы этот идентификатор будет возвращен (это удобно для внутреннего различения запросов внутри системы). Если идентификатор не передан, он будет сгенерирован автоматически.

Пример корректного запроса:

Сессия и авторизация

Авторизация в системе производится путем передачи тегов и в запрос типа «auth».
При этом, если указаны верные данные, система сгенерирует и вернет 64-символьный идентификатор сессии. Этот идентификатор необходимо в дальнейшем передавать системе в заголовках в виде cookie с названием sess_id.

Корректный запрос на авторизацию:

Запрос данных

Запрос данных имеет тип list. Каждая запрашиваемая структура должна быть обернута в тег с параметром name (названием структуры) и id (необязательно) — уникальный идентификатор запрашиваемой структуры (указание равносильно фильтрации по ключевому полю, см. ниже).

Ниже указано, как модифицировать запрос, чтобы получить только необходимые данные.

Выборка полей

Чтобы выбрать конкретные поля, добавьте в запрос тег и оберните в него теги с названиями полей (в том количестве и порядке, в котором они вам необходимы).

Пример ответа системы на подобный минимальный запрос:

Для выборки вложенных структур, передайте тег внутри тега с названием поля-указателя, затем примените правила из этого раздела. Количество уровней вложенности не ограничено. Указывать тип структуры на вложенных уровнях не требуется.

Упорядочивание, ограничение и фильтрация

Каждый тег рассматривается и обрабатывается в порядке указания.

Пример: Вывести контрагентов, упорядоченных по дате добавления, начиная с самого позднего:

Пример: Вывести не более 100 контрагентов, начиная с первого:

Получить список всех объектов системы

Получить структуру объектов системы

Запросить картинку

Фотография приходит в base64. Для получения картинки, поле в структуре должно быть «Указателем» на объект references.images

Например, запросить имя и фотографию сотрудников (поле — photo)

Запросить время на сервере

Отправка электронной почты из Системы

Прикрепление приложения

Прикрепление картинки

Для добавления картинки к объекту необходимо выбрать доступный «Тип изображения» (../settings/references/image_types), а также указать полное название объекта, его ID и поле с типом references.images (например: photo). Само изображение должно передаваться в base64.

При успешном выполнении запроса сервер вернет:

Создание заказа в CRM из интернет-магазина

При отправке данного запроса, машина автоматически проверяет наличие «Контрагента» в базе по 100% совпадению «Телефона» или «E-mail». При наличие совпадения, она создает «Счет» («Заказ») в найденном «Контрагенте», в противном случае она создает нового «Контрагента» и уже в нем создает «Счет» («Заказ»). Эту логику можно поменять, изменив файл в «Ядре», ответственный за API.

Внимание: Для работы данного запроса необходимо провести синхронизацию справочника «Номенклатуры» (Товаров) по id

Запрос цены и остатка товара

Корректный запрос на получение цены и остатка товара на складе:

где:
prod_id — id «Номенклатуры» (товара)
prod_price_id — id «Типа цены»
prod_stock_id — id «Склада»

где:
price — цена «Номенклатуры» (товара) в рублях, соответствующая запрошенному «Типу цен»
stock — остаток «Номенклатуры» (товара) на запрошенном «Складе»

Создание «Заявки» с сайта в Системе

Готовый примера и класса на PHP доступен по ссылке.

Экранирование XML символов

Для экранирования специальных символов типа « » необходимо обернуть вышеперечисленные символы в

Универсальный класс на PHP для доступа к API XML РосБизнесСофт XRM

Существует дополнительный класс для работы с XML API написанный на PHP. Класс доступен по ссылке.

Для начала работы с классом необходимо создать подключение к Системе (авторизация):

$url — Полный путь к API. Например: «https://mycrm.ru/api/xml»
$login — логин пользователя в программе
$password — пароль пользователя в программе

Для выборки данных используется метод:

$structure — название структуры
$fields — массив полей, для выборки полей используется следующий синтаксис:
array(“id”, “name”, “surname”)
$filters — массив фильтров, для фильтрации результатов, используется следующий синтаксис:
array(array(“field”=>”id”, “operation”=>”=”, “value”=>”1”))

Для добавления данных используется метод:

$structure — название структуры
$fields — массив полей, для добавления значения полей используется следующий синтаксис:
array(«name» => «Вася», «surname» => «Пупкин»)

*не рекомендуется задавать явно поле id, поскольку это первичный ключ, система поддерживает работу с этим поле самостоятельно.

Для редактирования данных используется метод:

$structure — название структуры
$fields — массив полей, для добавления значения полей используется следующий синтаксис:
array(“name”=>”Вася”, “surname”=>”Пупкин”)
$filters — массив фильтров, для фильтрации изменяемых полей, используется следующий синтаксис:
array (array(«field» => «id», «operation» => «=», «value» => «1»))

Остальные методы подробно описаны в самом классе.

Последние правки: 17.05.2021 15:46:15

Источник