Компонент «XML API»¶

Содержание

Компонент «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&param=789989

По умолчанию отчет экспортируется без заголовков (верхних и боковика). При необходимости включить заголовки нужно добавить параметр headers с любым значением. Тогда строка параметров будет выглядеть так:

param=123&param=789989&headers=true

Пример запроса к серверу (по адресу: http://system.sample.com) для экспорта отчета с id=34678 и двумя параметрами:

curl -X GET http://system.sample.com/api/1/34678/?param=123&param=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.