Компонент «XML API»¶
Содержание
Компонент обеспечивает программный интерфейс доступа к отчетам, формам и реестрам Системы. Работа с данными идет на уровне матриц (таблиц) чисел, а не на уровне структуры данных или показателей.
Сервис экспорта данных позволяет получить данные из табличного представления (отчета, формы или реестра) в виде таблицы чисел. Для экспорта необходимо знать идентификатор отчета/формы/реестра, его параметры (если они есть) и смысл данных в самом отчете/форме/реестре. Сервис экспорта не предоставляет информации о структуре табличного представления, то есть о том, какие показатели и фильтры используются в его строках и столбцах.
Сервис импорта данных позволяет записать (удалить, обновить) данные в заданной форме или реестре. Аналогично экспорту, работа идет на уровне таблицы чисел и необходимо знать смысл формы/реестра, в которые импортируются данные.
Технические особенности решения¶
Triafly выступает в роли сервера, а внешняя информационная система (далее «ИС») - в роли клиента.
Компонент «XML API» обеспечивает программный интерфейс доступа к данным Triafly по протоколу HTTP. Передаваемые данные представляются в формате XML.
Чтобы получить или передать данные Triafly, внешняя система обращается к серверу Triafly с запросом GET или POST соответственно.
Авторизация проходит по ключу из заголовка запроса.
Ограничение доступа внешней ИС к данным обеспечивается стандартными средствами платформы Triafly.
Обмен запросами можно осуществлять разными способами, например, с помощью командной строки curl.
Подготовка к интеграции¶
В системе Triafly:
- Должен быть создан пользователь, от лица которого будут происходить операции импорта и экспорта данных.
- Построены отчеты/формы/реестры, с которыми будет проводится интеграция.
- Пользователь должен обладать соответствующими правами на работу с этими отчетами/формами/реестрами.
- Пользователю должен быть присвоен API-ключ.
Клиентской стороне необходима следующая информация:
- URL системы Triafly.
- Api-ключ.
- Идентификатор отчета/реестра с данными для экспорта или формы/реестра для импорта данных.
- В случае, если отчет/форма/реестр имеет параметры - порядок параметров и их возможные значения (для параметров-справочников - идентификаторы элементов справочника, см. подраздел «Вывод id элементов справочника»).
Авторизация¶
Для авторизации запросов к серверу Triafly используется ключ авторизации пользователя, представляющего внешнюю ИС.
Авторизация для сервисов экспорта и импорта происходит одинаково: при совершении запроса нужно проставить в HTTP-заголовке ключ авторизации Netdb-Api-Key.
Пример запроса на экспорт данных с ключом авторизации:
curl -X GET http://127.0.0.1:8000/api/1/359262 -H "Netdb-Api-Key:XaPpwNWzNE"
При ошибке авторизации возвращается ответ со статусом 200, в xml:
<?xml version="1.0" encoding="UTF-8"?>
<error kind="auth">
</error>
Сервис экспорта данных¶
Для экспорта данных используется метод GET.
Запрос на экспорт данных¶
URL формируется следующим образом:
http://<host>/api/<v>/<id>/?<params>
где
- Вместо <host> подставляется URL сервера Triafly.
- Вместо <v> подставляется версия XML API. На текущий момент v=1.
- Вместо <id> подставляется идентификатор отчета, который нужно экспортировать (в интерфейсе Системы идентификатор отчета - это набор цифр после последнего символа «/» в url страницы просмотра данного отчета).
- Вместо <params> подставляется строка параметров отчета.
Строка параметров содержит список параметров отчета с разделителем «&». Для каждого параметра указывается идентификатор показателя, соответствующего данному параметру. В строке параметров отчета параметры следуют в том же порядке, что и параметры в интерфейсе Triafly при просмотре данного отчета.
Пример строки параметров для отчета с двумя параметрами:
param=123¶m=789989
По умолчанию отчет экспортируется без заголовков (верхних и боковика). При необходимости включить заголовки нужно добавить параметр headers с любым значением. Тогда строка параметров будет выглядеть так:
param=123¶m=789989&headers=true
Пример запроса к серверу (по адресу: http://system.sample.com) для экспорта отчета с id=34678 и двумя параметрами:
curl -X GET http://system.sample.com/api/1/34678/?param=123¶m=789989 HTTP/1.1 -H "Netdb-Api-Key:fasdf6sa7df8sdf67d8df687f6dfdaa"
Ответ на запрос в случае успешного экспорта¶
Ответ на запрос приходит в формате xml. При успешном экспорте ответ содержит элемент верхнего уровня data, элемент params (если у отчета есть параметры, в них перечислены параметры, которые были в get-запросе), и элемент table, устроенный как таблица в HTML. В tr лежат строки, а сами значения содержатся в элементах td:
<?xml version="1.0" encoding="UTF-8"?>
<data>
<params>
<param>123</param>
<param>789989</param>
</params>
<table>
<tr>
<td></td>
<td>55</td>
<td>59</td>
</tr>
<tr>
<td>88</td>
<td>99</td>
<td>890</td>
</tr>
<tr>
<td>44</td>
<td>55</td>
<td></td>
</tr>
</table>
</data>
Если для построения запрошен отчет с заголовками (в get-параметрах есть headers), то заголовки будут обозначены элементами th, у которых могут быть атрибуты rowspan и colspan - их смысл аналогичен атрибутам тега th в HTML. Пример:
<?xml version="1.0" encoding="UTF-8"?>
<data>
<params>
<param>123</param>
<param>789989</param>
</params>
<table>
<tr>
<th colspan="2">Общий заголовок</th>
</tr>
<tr>
<th>Первый столбец</th>
<th>Второй столбец</th>
</tr>
<tr>
<th rowspan="2">Первые две строки</th>
<th>Первая строка</th>
<td></td>
<td>55</td>
<td>59</td>
</tr>
<tr>
<th>Вторая строка</th>
<td>88</td>
<td>99</td>
<td>890</td>
</tr>
<tr>
<th colspan="2">Третья строка</th>
<td>44</td>
<td>55</td>
<td></td>
</tr>
</table>
</data>
Ограничение доступа к данным¶
Если в ячейке отчета есть значение, но у пользователя Triafly, от имени которого производится операция, нет прав на просмотр этого значения, то в ячейке экспортированной таблицы будет пусто.
Ответ на запрос в случае ошибки при задании параметров¶
При неправильном количестве параметров возвращается сообщение об ошибке. Например:
<?xml version="1.0" encoding="UTF-8"?>
<error kind="params">
Ожидалось параметров: 3, получено параметров: 0
</error>
При ошибке в формате значений параметров возвращается ответ, который содержит исходные значения параметров и пояснение об ошибке. Например:
<?xml version="1.0" encoding="UTF-8"?>
<error kind="value_format">
<params>
<param>97896</param>
<param error="Введите дату в формате, принятом в Системе">2011</param>
</params>
</error>
Сервис импорта данных¶
Для импорта данных используется метод POST.
Запрос на импорт данных¶
URL формируется следующим образом:
http://<host>/api/<v>/<id>
где
- Вместо <host> подставляется имя сервера Triafly.
- Вместо <v> подставляется версия XML API. На текущий момент v=1.
- Вместо <id> подставляется идентификатор формы/реестра, который нужно экспортировать (в интерфейсе Системы идентификатор формы/реестра - это набор цифр после последнего символа «/» в url страницы просмотра данной формы/реестра).
Импортируемые данные передаются в xml-формате, аналогичном формату экспортируемых табличных данных (см. выше подраздел Ответ на запрос в случае успешного экспорта).
Элемент верхнего уровня - data. Если у отчета есть параметры, то первый вложенный элемент - params. Внутри него должно быть столько элементов param, сколько параметров есть у отчета. Внутри элемента param указывается значение соответствующего параметра отчета.
Если параметров нет, то и элемента params быть не должно, а его наличие будет считаться ошибкой.
Далее следует обязательный элемент table, организованный также, как в HTML. Внутри него должно быть столько элементов tr, сколько есть строк в отчете. Внутри каждого tr должно быть столько td, сколько в отчете столбцов. Внутри каждого td указывается значение в данной ячейке отчета. Если значение пустое (пустая строка), а в Системе в этой ячейке есть значение, то подразумевается удаление этого значения.
Передаваемые данные кодируются в формате application/x-www-form-urlencoded.
Пример запроса к серверу (по адресу: http://system.sample.com) для импорта данных в форму с id=7715257 с одной строкой и двумя столбцами:
curl -X POST -H 'Netdb-Api-Key: HbzTyZVLYz' -i --data 'data=<data><table><tr><td>20</td><td>35</td></tr></table></data>' 'http://system.sample.com/api/1/7715257/'
Пример данных в формате xml для формы с двумя параметрами, тремя строчками и двумя столбцами:
<?xml version="1.0" encoding="UTF-8"?>
<data>
<params>
<param>97896</param>
<param>2011 г.</param>
</params>
<table>
<tr>
<td></td>
<td>59</td>
</tr>
<tr>
<td>99</td>
<td>890</td>
</tr>
<tr>
<td>44</td>
<td></td>
</tr>
</table>
</data>
Ответ на запрос в случае успешного импорта¶
Ответ от сервера приходит со статусом 200 независимо от ошибок в запросе клиента.
При успешном импорте данных возвращается ответ следующего вида (в атрибутах updated, created и deleted указано соответственно число обновленных, созданных и удаленных объектов):
<?xml version="1.0" encoding="UTF-8"?>
<data updated="4" created="1" deleted="1">
</data>
Ответ на запрос в случае ошибки в формате xml¶
При ошибке в формате xml возвращается сообщение об ошибке («Невалидный XML» или «Не найден элемент data» и т.п.):
<?xml version="1.0" encoding="UTF-8"?>
<error kind="invalid_request">
Невалидный xml
</error>
Ответ на запрос в случае ошибки в формате значений¶
При ошибке в формате значений (не важно, параметров или данных в клетках таблицы) возвращается исходный запрос в элементе error, где к ошибочным полям (элементы params или td) добавлен атрибут error, поясняющий смысл ошибки. Текст ошибки аналогичен тексту ошибок в web-интерфейсе Системы.
Ответ на запрос в случае ошибки в правах доступа¶
При ошибке в правах доступа к полям (к элементу td) добавляется атрибут permission_error, содержащий сообщение об ошибке:
<?xml version="1.0" encoding="UTF-8"?>
<error kind="value_format">
<params>
<param>97896</param>
<param error="Введите дату в формате...">2011</param>
</params>
<table>
<tr>
<td></td>
<td error="Введите целое число">78.3</td>
<td>59</td>
</tr>
<tr>
<td permission_error="У вас нет прав на запись в показатель...">88</td>
<td>99</td>
<td>890</td>
</tr>
<tr>
<td>44</td>
<td>55</td>
<td></td>
</tr>
</table>
</error>
При наличии хотя бы одной ошибки сохранение данных не происходит.
Импорт в реестры¶
Реестры отличаются от отчетов и форм тем, что у них не задано количество строк. Поэтому для поддержки как обновления, так и добавления данных в реестр, вводятся новые элементы: keys и key.
Для обновления данных в реестре необходимо указать, какой набор его столбцов считать ключом. Если такой набор столбцов задан, и для определенной записи в этом реестре при импорте находится запись с такими же значениями ключевых столбцов, то происходит обновление этой записи. Если же такой записи нет или ключи не указаны, происходит добавление записи в реестр.
Для описания ключей к элементу data нужно добавить элемент keys. Внутри него должен находиться один или более элемент key, значение которого - индекс столбца реестра (индекс начинается с нуля, т.е. первый столбец имеет индекс 0, второй столбец - индекс 1 и т.д.).
Пример запроса на импорт с ключами (ключ записи - комбинация первого и второго столбцов):
<?xml version="1.0" encoding="UTF-8"?>
<data>
<params>
<param>97896</param>
</params>
<keys>
<key>0</key>
<key>1</key>
</keys>
<table>
<tr>
<td>218</td>
<td>55.238</td>
<td>2010 г.</td>
</tr>
<tr>
<td>218</td>
<td>57.813</td>
<td>2011 г.</td>
</tr>
</table>
</data>
При недопустимом индексе ключевого столбца (в случае, когда данный реестр не имеет столбца с указанным индексом) возвращается сообщение об ошибке, где к соответствующему элементу key добавляется атрибут error:
<?xml version="1.0" encoding="UTF-8"?>
<error>
<params>
<param>97896</param>
</params>
<keys>
<key>0</key>
<key error="Недопустимый индекс столбца">3</key>
</keys>
<table>
<tr>
<td>218</td>
<td>55.238</td>
<td>2010 г.</td>
</tr>
<tr>
<td>218</td>
<td>57.813</td>
<td>2011 г.</td>
</tr>
</table>
</error>
Если данный набор столбцов ключом не является, т.е. если в реестре уже существуют два объекта с такими ключами, то выдается сообщение об ошибке. В остальном импорт в реестр происходит так же, как импорт в отчет или форму.
Форматы значений данных и параметров¶
Форматы и примеры для всех типов значений, которые используются в данных (в элементах td) или в значениях параметров (в элементах param):
- Число - десятичное число с плавающей точкой, разделителем является точка или запятая. Пример: «3.12159265». Возможно также представление в экспоненциальном виде: «6.022e23».
- Целое - десятичное число, может быть отрицательным. Пример: «60», «-127».
- Объект - идентификатор объекта или целое число (может быть отрицательным). Идентификатор объекта можно узнать на странице объекта в соответствующем справочнике.
- Период - некоторый промежуток времени.
Форматы типов периодов:
- Год: 2012 г.
- 3 квартала: 1 кв. 2012 г. - 3 кв. 2012 г.
- Полугодие: 1 п. 2012 г.
- Квартал: 1 кв. 2012 г.
- Месяц: январь 2012 г.
- Декада: 2 декада января 2012 г.
- Неделя: с 17.01.2012 по 24.01.2012.
- День: 17.01.2012, 2012-01-17.
Работа с кросс-доменными запросами¶
Возможно обращение к XML API Системы из стороннего web-интерфейса. API работает с кросс-доменными запросами, поддерживает метод OPTIONS и необходимые заголовки запроса, который автоматически посылается браузером перед исполнением кросс-доменного запроса (подробнее см. на https://learn.javascript.ru/xhr-crossdomain).
Вывод id элементов справочника¶
При передаче параметров через XML API необходимо указывать id элементов справочника, а не их названия. Получить id элементов можно следующим образом.
Для вывода ID элементов справочника «Показатели» нужно создать в Системе 2 показателя: «Промежуточный показатель» и «ID элемента».
- «Промежуточный показатель» типа «Справочник» со значениями из справочника «Показатели».

Затем нужно поставить галочку «Автоматически ссылаться на элементы справочника» для созданного показателя в справочнике «Показатели».

- «ID элемента» типа «Целое» с формулой: «ID элемента»=ЦЕЛОЕ(Промежуточный показатель).

Затем составить отчет:
- В заголовках строк фильтр «Промежуточный показатель» с указанной опцией «задание формулой».
- В заголовках столбцов источник «ID элемента».
После настройки в отчете будут представлены данные: название элемента справочника «Справочник», id элемента справочника «Показатели».

Аналогично настраивается отчет для вывода id элементов любого справочника. Для этого необходимо выбрать нужный справочник в шаге «значения из справочника» при создании показателя «Промежуточный показатель».
Отчет можно сохранить, выгрузить в xls, csv, xml, обращаться к нему через API.