XML інтерфейс

• Терміни в тексті виділяються курсивом. Наприклад: це термін.
• Зарезервовані слова, назви елементів і атрибутів виділяються жирним шрифтом. Наприклад: це зарезервоване слово.

Загальні поняття

Базовим інтерфейсом системи Депозитарію є XML інтерфейс, який забезпечує максимальну функціональність при роботі з системою. Призначення XML-інтерфейсу:

• забезпечення роботи системи Депозитарію (зокрема візуальних засобів адміністрування Депозитарію);
• надання зовнішнім прикладним програмам доступу до даних та сервісів Депозитарію;
• для інтеграція системи Депозитарію з зовнішніми інформаційними системами;
• робота із системою за допомогою спеціалізованого програмного забезпечення.

Взаємодія між прикладною програмою та Депозитарієм відбувається шляхом обміну між ними повідомленнями в форматі XML.

Усі повідомлення повинні відправлятися методом "POST" з використанням типу даних "text/xml". Крім цього в заголовку кожного HTTP запиту передаються параметри необхідні для авторизації користувача.

Інтерфейс проводить авторизацію користувача і створює для нього сесію роботи з системою.

У випадку якщо користувач не проходить авторизацію інтерфейс формує відповідний код помилки і припиняє обробку даного повідомлення. Якщо авторизація пройшла успішно, інтерфейс виконує отриманий запит.

Результат виконання запиту повертається користувачеві також у форматі XML.

Терміни та визначення XML – протоколу

Правильний XML-документ

 Правильний XML-документ (well-formed XML-документ) це документ, який відповідає стандартам оформлення XML-документів, які викладено на http://www.w3.org/TR/REC-xml (англійською мовою) або на http://www.rol.ru/news/it/helpdesk/xml01.htm (російською мовою).

Повідомлення та повідомлення-відповіді мають бути правильними XML-документами.

Запит

Запит – мінімальна одиниця операцій з базою даних. Це означає, що він має бути виконаний лише цілком і без помилок, інакше запит вважається помилковим.

Кожен запит отримує свій унікальний ідентифікатор. В залежності від типу запиту ідентифікатор або генерується автоматично, або запитується в користувача.

В XML запит – це один XML-елемент (ім’я запиту є ім’ям тегу цього елементу, ідентифікатор записується в атрибут id). Запит складається з списку параметрів та необов’язкової області даних.

Виділяють дві групи запитів:

• на отримання даних,
• на модифікацю даних .

В першому випадку відповідь вміщуватиме дані, задля отримання яких було сформовано запит.

В другому випадку, якщо модифікація даних пройшла успішно, відповідь буде пустою.

За допомогою запитів система веде журнал дій користувача.

Запиту можна задати мнемонічне ім’я за допомогою атрибута alias. Цей атрибут буде скопійовано в повідомлення відповідь.

Повідомлення

Повідомлення - це мінімальний пакет, який може бути відісланий клієнтом на сервер. Воно складається з деякого числа запитів, кожен з яких обробляється незалежно. Якщо повідомлення складається з великої кількості запитів з однаковим ім’ям, для спрощення співставлення відповіді з запитом останньому можна задати мнемонічне ім’я.

Існує обмеження на кількість запитів , які виконані з помилками, в одному повідомленні.

 При виникненні критичної кількості помилок Депозитарій генерує помилку №16 TOO_MANY_ERRORS, яка повертається користувачеві в повідомленні-відповіді. Виконання запитів при цьому завершується.

Як результат обробки повідомлення формується та відсилається клієнту повідомлення-відповідь.

Повідомлення-відповідь

Повідомлення-відповідь – результат обробки повідомлення користувача сервером.

Повідомлення-відповідь складається з списку відповідей (результатів обробки запитів) або повідомлення про полики (у тому випадку, якщо повідомлення було отримане у некоректному форматі або в результаті його обробки відбулись помилки загального характеру, тобто помилки, що не пов’язані з конкретним запитом).

На кожен запит формується відповідь. Відповіді записуються в повідомлення відповідь в тому ж порядку, в якому були записані запити у повідомленні.

В тому випадку, коли не вдається обробити конкретний запит, на місце відповіді записується повідомлення про помилку.

Повідомлення-відповідь є правильним (well-formed) XML-документом.

Відповідь

Відповідь – XML-елемент у повідомленні-відповіді. Відповідь генерується в результаті виконання запиту.

Ім’я тегу відповіді співпадає з ім’ям запиту. Зміст елементу відповіді повністю залежить від того, який запит виконувався.

Якщо запит був сформований для отримання даних тег вміщуватиме дані згідно запиту.

Якщо запит був сформований для модифікації даних він у більшості випадків буде пустим.

Якщо в результаті обробки запиту виникла помилка, у відповіді буде присутній елемент error , який складатиметься з коду помилки та діагностичного повідомлення.

Одночасно з елементом error у відповіді може бути розміщена частина запиту, в якій відбулася помилка. В цьому випадку елемент error включається у цей фрагмент коду запиту.

Робота з XML інтерфейсом Депозитарію

Інформація про інтерфейс

Також існує можливість отримувати результат(тільки для запитів GetGLN та GetGTIN) у форматі XML-схем EAN·UCC версії 1.3.1 через інтерфейс, який знаходиться за адресою:
http://depos.gs1ua.org/interface/ean
Адреса інтерфейсу для сайту Демо-Депозитарію:
http://depdemo.gs1ua.org/interface/ean

Опис запитів, доступних користувачам, представлений у вигляді ХML-схеми та доступний за адресою:
http://depdemo.gs1ua.org/xsd/userrequest.xsd
Опис метаданих інформації, що знаходиться у Депозитарії, представлений у вигляді ХML-схеми та доступний за адресою:
http://depos.gs1ua.org/xsd/metadata.xsd

Робота з XML консоллю депозитарію

Для ознайомлення з XML протоколом краще всього використовувати XML консоль в розділі "Мій Депозитарій".
Там же знаходиться приклад запиту "GetMyUserInfo", який дозволяє отримати інформацію про поточного користувача.

Модуль XML консолі призначений для виконання будь-яких запитів до системи депозитарію.

Використовуючи цей модуль, користувач може виконувати запити, доступні через XML інтерфейс для цього користувача.

Цей модуль може використовуватися для відпрацювання XML-повідомлень при налагодженні інформаційної системи користувача для зв'язку з депозитарієм.

XML консоль дозволяє користувачеві написати за допомогою вбудованого редактора текст будь-якого запиту у форматі XML, виконати його та одержати результат його роботи у форматі XML.

Для отримання результату повідомлення необхідно натиснути кнопку „Відправити запит”. У полі „Результат запиту” формується повідомлення-відповідь за механізмом, який описано в пункті „Повідомлення-відповідь”.