Войти
Назад

Обмен сообщениями с помощью REST API (Web-сервис)

link
Скопировать прямую ссылку на статью

Для отправки и приема сообщений в СМЭВ посредствам интеграционного узла адаптера (ИУА) можно использовать несколько интерфейсов, в том числе интерфейс «Web-сервис». Web-сервис ИУА реализован для обеспечения информационного взаимодействия по SOAP или REST API протоколу. В текущей статье будут рассмотрены примеры обменов по REST API – технологии на примере работы в приложении Postman.

 

Установка и подготовка Postman

После установки интеграционного узла адаптера (ИУА) необходимо установить программу Postman, воспользовавшись официальным дистрибутивом. После установки и запуска приложения будет предложено авторизоваться. Этот этап можно пропустить, выбрав опцию использования приложения без авторизации в нижней части окна приложения. Дальше необходимо создать коллекцию запросов (File → New → Collection), в которой будут размещены все необходимые запросы (Рисунок 1).


 Рисунок 1 – Создание новой коллекции в Postman.

Для добавления запроса навести на только что созданную коллекцию и по кнопке дополнительного меню выбрать пункт добавить запрос (Рисунок 2).


 Рисунок 2 – Создание нового запроса.

В новой открывшейся вкладке запроса можно будет изменить название самого запроса, метод формирования HTTP-запроса, адрес обращения и др. (Рисунок 3).

 Рисунок 3 – Окно созданного запроса.


Список доступных методов

Существует три доступных варианта взаимодействия с ИУА через REST API, к ним относятся методы Send (инициализация сообщения), Get (получение сообщения из очереди собственной ИС) и Find (поиск сообщения по заданным критериям).

Для обращения к ИУА по умолчанию будет использоваться основной URL–адрес: http://localhost:7590/ws с указанием метода, например http://localhost:7590/ws/get (при изменении порта обращения 7590 в конфигурации Адаптера на иной следует изменить URL-адрес соответственно). Дополнительно стоит отметить, что все данные будут передаваться в текстовом формате обмена данными JSON.

Для проверки работоспособности ИУА можно воспользоваться существующим видом сведения «Предоставление необходимой для уплаты информации». Для этого необходимо перейти по ссылке и скачать архив «Инструкции и файлы тестирования с эмулятором.zip», который потребуется распаковать и найти в нем эталонный конверт request. Так же для необходимо будет добавит в конверт поле с признаком тестового сообщения: testMessage: true, который необходимо будет добавить в элемент requestMetadata.

Отправка запросов и ответом методом Send

URL–адрес запроса: http://localhost:7590/ws/send

Важным этапом формирования запроса является вставка блока данных запроса в messagePrimaryContent → any. Сперва нужно взять эталонный запрос и отформатировать его в любом удобном редакторе, например, можно использовать Notepad++, используя поиск (Ctrl+F) с заменой элементов. Необходимо учесть следующие требования при изменении XSD-запроса:

  • сообщение должно быть одной строкой и не должно содержать каких-либо переносов строк;
  • все двойные кавычки должны быть обозначены как спец символы, другими словами перед каждой кавычкой необходимо поставить обратный слеш;
  • необходимые пробелы между атрибутами элемента должны быть соблюдены во избежание ошибок.

Описание основных полей блока данных запроса:

  • itSystem – код ИС в ИУА;
  • requestMessage– описание отправляемого запроса.

В элемент requestMessage входит:

  • messageType – тип сообщения (RequestMessageType);
  • requestMetadata → clientId – уникальный идентификатор запроса;
  • requestMetadata → testMessage – флаг, указывающий на тестовое сообщение, в случае его установки (true) запрос уйдет в эмулятор УВ и ответом будет эталонное сообщение;
  • routingInformation – блок маршрутной информации. Применим только для ВС с динамической маршрутизацией;
  • requestContent → content  - контейнер, включает в себя:
    • messagePrimaryContent → any – бизнес-данные запроса, сформированные по XSD-схеме ВС в формате XML;
    • attachmentHeaderList – контейнер с информацией о вложениях.

В качестве шаблона запроса может служить следующий пример конверта: 

{
 "itSystem": "MNEMONIC1",
 "requestMessage": {
   "messageType": "RequestMessageType",
   "requestMetadata": {
     "clientId": "00000000-0000-0000-0000-000000000000",
      "testMessage": true
   },
   "requestContent": {
     "content": {
       "messagePrimaryContent": {
         "any": "<tns:MyRequest xmlns:tns='urn://test/1.0.1'>
<tns:MyRequestString>test</tns:MyRequestString></tns:MyRequest>"
       }
     }
   }
 }
}

В результате успешного выполнения запроса должен служить следующий ответ от СМЭВ: 

{
 "itSystem": "MNEMONIC1",
 "messageId": "00000000-0000-0000-0000-000000000000"
}

Описание основных полей блока данных ответа:

  • itSystem – код ИС в ИУА;
  • responseMessage – описание отправляемого ответа.

В элемент responseMessage входит:

  • messageType – тип сообщения (ResponseMessageType);
  • responseMetadata → clientId – уникальный идентификатор запроса;
  • responseMetadata → replyToClientId – уникальный идентификатор запроса, на который направляется данный ответ;
  •  responseContent → content  - контейнер бизнес-данных запроса аналогичный формату запроса.

В качестве шаблона ответа с вложением может служить следующий пример конверта: 

{
 "itSystem": "MNEMONIC2",
 "responseMessage": {
   "messageType": "ResponseMessageType",
   "responseMetadata": {
     "clientId": "00000000-0000-0000-0000-000000000000",
     "replyToClientId": "00000000-0000-0000-0000-000000000000"
   },
   "responseContent": {
     "content": {
       "messagePrimaryContent": {
         "any": "<tns:MyResponse xmlns:tns='urn://test/1.0.1'>
<tns:MyResponseString>test</tns:MyResponseString></tns:MyResponse>"
       },
       "attachmentHeaderList": {
         "attachmentHeader": [
           {
             "filePath": "C:folderdocument.docx"
           }
         ]
       }
     }
   }
 }
}

Метод Get (получение запроса и очереди)

URL–адрес запроса: http://localhost:7590/ws/get

Описание основных полей метода получения запроса из собственной очереди:

  • itSystem – код ИС в ИУА;
  • routerExtraQueue – наименование очереди для получения ответа на запрос;
  • specificQuery → messageTypeCriteria – тип сообщения:
    • REQUEST – запрос;
    • RESPONSE – ответ.

В качестве шаблона получения запроса из очереди может служить следующий пример конверта: 

{
 "itSystem": "MNEMONIC1"
}

Метод Find (поиск запросов)

URL–адрес запроса: http://localhost:7590/ws/find

Описание основных полей метода поиска запросов:

  • isSystem – код ИС в ИУА;
  • specificQuery – контейнер, включает варианты запроса сообщений:
    • messagePeriodCriteria – включает временной диапазон, за который необходимо получить сообщения;
    • messageClientIdCriteria – контейнер временного диапазона, за который необходимо получить сообщения;
    • messageCountToReturn – количество сообщений, удовлетворяющих критериям поиска, которое необходимо вернуть;
    • messageOffset – размер смещения по списку сообщений или порядковый номер сообщения, с которого начнется отбор запросов.

В элемент messagePeriodCriteria входит:

  • from – метка времени, от которой искать сообщения;
  • to – метка времени, до которой искать сообщения.

В элемент messageClientIdCriteria входит:

  • clientId – уникальный идентификатор запроса;
  • clientIdCriteria – определяет тип запроса:
    • GET_REQUEST_BY_REQUEST_CLIENTID – получить запрос по клиентскому идентификатору запроса;
    • GET_RESPONSE_BY_RESPONSE_CLIENTID – получить ответы на запрос по клиентскому идентификатору ответа на запрос;
    • GET_RESPONSE_BY_REQUEST_CLIENTID – получить ответ на запрос по клиентскому идентификатору запроса.

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

{
 "itSystem": "MNEMONIC1",
 "specificQuery": {
   "messagePeriodCriteria": {
     "from": "2022-01-01T00:00:00+00:00",
      "to": "2022-01-10T00:00:00+00:00"
   },
   "messageCountToReturn": 10
 }
}

В качестве шаблона поиска запросов по идентификатору запроса может служить следующий пример конверта: 

{
 "itSystem": "MNEMONIC1",
 "specificQuery": {
   "messageClientIdCriteria": {
     "clientId": "00000000-0000-0000-0000-000000000000",
     "clientIdCriteria": "GET_REQUEST_BY_REQUEST_CLIENTID"
   }
 }
}
Авторизуйтесь, чтобы оставить комментарий к статье