Обмен в СМЭВ4 c использованием REST-сервиса

REST-сервисы в СМЭВ4

СМЭВ4 позволяет Поставщикам регистрировать создаваемые ими REST-сервисы для формирования регламентированных запросов (РЗ) к своим информационным системам (ИС) с использованием спецификации OpenAPI. При этом Поставщики имеют возможность ограничивать доступ Потребителей к своим REST-сервисам, управляя правами на взаимодействие через личный кабинет Участника взаимодействия (ЛК УВ). Подробнее об этом можно прочитать в Руководстве пользователя ЛК УВ (п. 5.14.4 «Добавление критериев доступа к регламентированным запросам типа REST-сервис»).

Механизм обмена по РЗ типа REST-сервис (далее – РЗ типа REST) проверяет соответствие запросов Потребителей и ответов Поставщиков зарегистрированной в СМЭВ4 спецификации OpenAPI. Также он позволяет ограничивать количество запросов к REST-сервисам Поставщиков и обеспечивает сохранение данных о запросах и ответах, возникающих в процессе информационного обмена.

Для реализации REST-сервисов в СМЭВ4 необходимо предварительно выполнить следующие шаги:

На стороне Поставщика

• разработать РЗ типа REST в соответствии с требованиями Потребителей;
• создать OpenAPI-спецификацию для работы с РЗ;
• зарегистрировать РЗ типа REST в СМЭВ4;
• задать критерии доступа к РЗ для Потребителей.

На стороне Потребителя

• сформировать запросы по РЗ типа REST в соответствии с OpenAPI-спецификацией, предоставленной Поставщиком;
• получить доступ к РЗ в соответствии с критериями, заданными Поставщиком.

Для организации обмена через СМЭВ4 Потребитель должен быть участником взаимодействия, иметь зарегистрированную ИС в СМЭВ и установленное типовое ПО «Агент СМЭВ4». Подробнее об этом читайте в статье «Как стать участником взаимодействия». После этого Потребитель может получить доступ к РЗ.

 Для получения доступа к спецификации в ЛК УВ в СМЭВ выполните следующие действия:

1.     Войдите в ЛК УВ под своей учетной записью.

2.     В «Быстрых действиях» перейдите на вкладку СМЭВ4.

Примечание

Потребитель может получить доступы одновременно к нескольким РЗ типа REST-сервис.

Рисунок 1 – Выбор действия «Массовое получение доступов к РЗ типа REST-сервис»

4.     Выберите среду, в которой будет выполняться обмен: тестовую или продуктивную (см. Рисунок 2).

Рисунок 2 – Выбор среды взаимодействия

5.     Выберите ИС. Если для вашей организации в ЛК УВ зарегистрировано несколько ИС, то для поиска нужной начните вводить в поле поиска ее наименование или мнемонику (см. Рисунок 3).

Рисунок 3 – Выбор ИС

6.     Найдите требуемый РЗ. Для облегчения поиска начните вводить в поле поиска наименование РЗ, его мнемонику или URL. Вы можете также найти РЗ по ОГРН, ИНН, наименованию или описанию организации-владельца РЗ.

Примечание

Владельцем РЗ является Поставщик.

7.     Поставьте флажок слева от РЗ, к которому требуется получить доступ (см. Рисунок 4). Если требуется получить доступы к нескольким РЗ из списка найденных, поставьте флажки слева от всех требуемых.
Нажмите Продолжить.

Рисунок 4 – Выбор РЗ

8.     Подтвердите запрос на получение доступа к выбранному РЗ (см. Рисунок 5).

Рисунок 5 – Подтверждение запроса на получение доступа к выбранному РЗ

В результате будет запущен процесс получения доступа (см. Рисунок 6).

Рисунок 6 – Информационное сообщение о запуске процесса получения доступа к РЗ

В ЛК УВ Потребителя будет отображаться название РЗ, к которому запрошен доступ, и статус получения доступа к нему, например: «Регистрация доступа в СМЭВ4» или «Доступ к РЗ получен» (см. Рисунок 7).

В продуктивной среде отправляется заявка Поставщику для согласования доступа.

Рисунок 7 – Статус получения доступа к РЗ

После получения доступа к РЗ в ЛК УВ Потребителя станет доступен файл спецификации этого РЗ.

Для организации обмена через СМЭВ4 Поставщик должен быть участником взаимодействия, иметь зарегистрированную в СМЭВ информационную систему (ИС) и установленное типовое ПО «Агент СМЭВ4». Подробнее об этом читайте в статье «Как стать участником взаимодействия».

После этого Поставщику необходимо разработать OpenAPI-спецификацию для РЗ, зарегистрировать РЗ в СМЭВ и настроить права доступа к нему для Потребителей.

OpenAPI-спецификация для РЗ типа REST создается в виде текстового файла в формате JSON или YAML. При разработке спецификации определяются HTTP-методы, параметры, ответы и структуры передачи данных в запросах и ответах, которые будет предоставлять REST-интерфейс взаимодействия. С форматом документирования REST-обменов OpenAPI, пошаговым описанием составления спецификации и с подробным разбором каждого блока можно ознакомиться в статье «Как создать свою спецификацию OpenAPI» и в «Методических рекомендациях по работе с СМЭВ4» (п. 1.5.6 «REST-сервисы ИС Ответчиков»).

Для создания РЗ типа REST необходимо зарегистрировать сформированную для него OpenAPI-спецификацию в ЛК УВ, после чего можно будет настроить права доступа к ней для ИС Потребителей.

Для регистрации РЗ в ЛК УВ:

1.     Войдите в ЛК УВ под своей учетной записью.

2.     Перейдите на вкладку СМЭВ4.

3.     В «Быстрых действиях» выберите панель Создать регламентированный запрос REST-сервис (см. Рисунок 8).

Рисунок 8 – Выбор действия «Создать РЗ типа REST-сервис»

4.     Выберите среду взаимодействия в СМЭВ4: тестовую или продуктивную (см. Рисунок 9).

Рисунок 9 – Выбор среды взаимодействия в СМЭВ4

5.       Создайте новый РЗ в выбранной среде (см. Рисунок 10).

Рисунок 10 – Создание нового РЗ

6.       Укажите ИС, которая будет выступать в качестве Поставщика данных. Для выбора ИС из набора доступных систем в поле поиска начните вводить ее наименование или мнемонику (см. Рисунок 11).

Рисунок 11 – Выбор ИС

7.       Для создаваемого РЗ укажите в соответствующих полях его название и префикс в URL. Рекомендуется выбирать название, которое кратко описывает суть взаимодействия. Префикс должен начинаться с косой черты и содержать название на латинице, например: /openapi-testing (см. Рисунок 12).

 

Рисунок 12 – Название РЗ и его префикс в URL

Примечание

В случае ошибок в процессе заполнения форм система будет отображать подсказки (см. Рисунок 13).

Рисунок 13 – Пример подсказки

8.       Загрузите в форму создания РЗ ранее созданный файл OpenAPI-спецификации, выбрав его на компьютере (см. Рисунок 14).

Рисунок 14 – Загрузка файла спецификации

9.       После успешной загрузки документа подтвердите создание нового РЗ типа REST-сервис (см. Рисунок 15).

Рисунок 15 – Подтверждение создания нового РЗ

В результате новый запрос будет успешно создан (см. Рисунок 16).

Рисунок 16 – Информационное сообщение о создании РЗ

Созданный РЗ будет отображаться в списке всех РЗ в ЛК УВ Поставщика (см. Рисунок 17).

Рисунок 17 – Просмотр списка РЗ в ЛК УВ Поставщика

После создания РЗ добавьте критерии доступа к нему для Потребителей.

Подробнее о том, как создать РЗ типа REST-сервис, как добавить критерии доступа и как предоставить доступы для Потребителей, читайте в «Руководстве пользователя ЛК УВ» (п.п. 5.14 – 5.17).

Информационный обмен через API Gateway для выполнения запросов через REST-сервис является для Агента СМЭВ4 опциональным. Начиная с версии Агента 3.14, эта возможность по умолчанию не включена.

Чтобы включить обмен через REST-сервис, необходимо внести изменения в конфигурационный файл Агента СМЭВ4 (application.yml). В этот файл нужно добавить блок настроек api-gateway, приведенный в примере ниже. В данном блоке необходимо указать адрес расположения и порт REST-сервиса, на который Агент будет перенаправлять все поступающие запросы типа REST-сервис.

Пример блока настроек Агента СМЭВ4 для включения обмена через REST-сервис:

api-gateway: client:     impl: APACHE     options:       default-host: 'localhost'       default-port: '1234'       ssl: false       verifyHost: false       maxPoolSize: 100

В этом блоке:

-       default-host – адрес расположения REST-сервиса Агента

-       default-port – порт REST-сервиса Агента.

После внесения изменений в файл конфигурации необходимо перезапустить Агент СМЭВ4.

Подробнее об особенностях конфигурирования API Gateway при работе по HTTP или HTTPS можно прочитать в «Руководстве администратора Агента СМЭВ4» в разделе 4.3.9 «Настройка организации информационного обмена через API Gateway».

Формат запроса для обмена с использованием REST-сервиса ИС Поставщика имеет вид:

<HTTP-метод> <адрес>:<порт>/<systemMnemonic><basePath><path>

где:

-       HTTP-метод – метод из поддерживаемых REST-сервисом;

-       <адрес> – IP-адрес Агента Потребителя;

-       <порт> – порт для обращения Агента Потребителя к Ядру СМЭВ4 в соответствии с «Руководством администратора СМЭВ4»;

-       <systemMnemonic> – мнемоника Агента Поставщика, на стороне которого развернут REST-сервис;

-       <basePath> – префикс в URL соответствующего REST-сервиса ИС Поставщика;

-       <path> – путь операции, указанный в спецификации OpenAPI соответствующего REST-сервиса ИС Поставщика.

Подробнее об этом можно прочитать в «Методических рекомендациях по работе с СМЭВ4» ( п. 3.4 «Выполнение запросов к REST-сервису ИС Ответчика»).

Рассмотрим пример формирования REST-запроса Потребителем, использующим следующие параметры:

-       адрес обращения к Агенту – localhost;

-       порт OpenAPI по умолчанию – 8171;

-       мнемоника ИС Поставщика – MNEMONIC;

-       префикс в URL – /openapi-testing;

-       путь REST-запроса – /api.

Потребитель составит следующий URL-адрес, который будет отправлен в СМЭВ4 в составе REST-запроса:

localhost:8171/MNEMONIC/openapi-testing/api

Сам REST-запрос будет выглядеть следующим образом:

GET localhost:8171/MNEMONIC/openapi-testing/api

После успешной проверки Ядром СМЭВ4 наличия REST-запроса и доступов для ИС Потребителя запрос будет перенаправлен к Агенту СМЭВ4 Поставщика.

Пример ответа на запрос приведен на рисунке ниже (см. Рисунок 18).

Рисунок 18 – Пример успешного ответа на запрос