REST API

REST API коннектор внешней системы даёт возможность подключить к системе собственный REST сервис с методами, описанием типов.

Для создания внешней системы:

  1. В ЦН перейдите в раздел Интеграция -> Внешние системы.

2. Нажмите на кнопку +. В рабочей области страницы отобразится интерфейс создания / редактирования новой внешней системы, содержащий три вкладки: Основная, Коннекторы и Обработчики:

../../_images/image74.png

  1. На вкладке Основная заполните следующие поля:

  • Имя: уникальное имя системы, обязательно для заполнения.

  • Название: произвольное название системы, обязательно для заполнения.

  • Комментарий: описание системы, необязательно для заполнения.

  • Правило обработки очередей: идентификатор правила обработки очередей, заполняется в соответствии с требованиями системы.

  • Серверы: названия серверов, заполняется в соответствии с требованиями системы.

  1. Убедитесь, что флажок Включен установлен.

Примечание

По умолчанию флажок установлен. Если не предполагается вводить все необходимые данные для этой системы, флажок следует убрать и установить только по окончании ввода данных.

  1. Перейдите на вкладку Коннектор.

  2. Выберите тип Расширенное REST API:

../../_images/image94.png

  1. Укажите количество потоков передачи в соотвествующем поле.

  2. При необходимости установите флажки Использовать http и Требовать авторизацию.

Дополнительная настройка работы системы производится в режиме редактора конфигурации.

Внимание

Перед переходом в режим редактора конфигурации сохраните внесенные данные!

  1. В верхней правой части рабочего пространства расположены кнопки Перейти в режим редактора конфигурации и Сохранить. Нажмите на кнопку Сохранить. Введенные данные будут сохранены, и между кнопками появится кнопка Обновить, которую можно будет использовать для обновления данных:

    ../../_images/config_upd_save1.png

  2. Перейдите в режим редактора конфигурации, нажав на соответствующую кнопку:

../../_images/image801.png

Система типа REST API позволяет настроить пользовательское API с любым набором веб-методов.

  1. В блоке config укажите необходимый тип конфигурации адаптера. Все актуальные примеры настроек можно взять из swagger ЦН, контроллер XampleSystemConfig GET/examples/adapters/web Web Адаптер

  2. Настройте следующие параметры:

  • port - порт, на котором будет запущено веб-API. Должен быть уникальным в пределах одной машины. Значение задается вручную (в примере ниже используется порт 6633).

  • useHttps - использовать ли https при публикации. При true будет использован сертификат, указанный при установке.

  • replyStoreTime - время хранения сообщений, на которые не был получен ответ до истечения таймаута. Если обработчик ожидает ответа и в течение указанного таймаута ответ не приходит, то в ответе возвращается идентификатор сообщения. Если идентификатор сообщения известен, его можно передать в метод GET/{messageId} адаптера (контроллер CheckRequestState), который вернет или полученный ответ, или код ошибки.

  • auth - настройки аутентификации для обработчиков с флагом Требуется авторизация. При usePasswordHash: true для авторизации нужно передавать не сам пароль, а только хеш от него (SHA256 в шестнадцатеричном формате). Для включения авторизации необходимо наличие в кластере активного модуля Хранения учетных данных.

  • publishSwagger - настройка публикации swagger. При значении false он не публикуется, но при этом методы работают как и раньше. Swagger для данной конфигурации откроется по адресу (При условии publishSwagger=true): https://localhost:6633/swagger/index.html

После создания системы можно добавить обработчики типа Веб-обработчик. Это можно сделать из редактора обработчика (вкладка Системы) или из редактора системы (раздел handlersList)

  1. После внесения данных нажмите на кнопку Сохранить.

  2. Нажмите на кнопку Применить конфигурацию:

    ../../_images/config_apply1.png

Свойства сообщения, зависимые от настроек обработчика

  • IsArray - принимает значение true если выставлен флаг массив у запроса.

  • DataType - содержит идентификатор пользовательского типа, если запрос является объектом этого типа.

  • SystemDataType - содержит идентификатор типа метаданных, если запрос является объектом этого типа.

  • Body - содержит массив байт запроса, доступно только через методы.

  • Свойства сообщения:

    • AnswerRequired - принимает значение true, если установлен флаг ожидание ответа или заполнена переменная на вкладке Ответ. Получение значения осуществляется через метод GetBoolOrNullProperty(«AnswerRequired»).

    • AnswerDataType - содержит идентификатор типа данных, если ответ является объектом этого типа. Получение значения осуществляется через метод GetStringOrNullProperty(«AnswerRequired»).

    • AnswerSystemDataType - содержит идентификатор типа метаданных, если ответ является объектом этого типа. Получение значения осуществляется через метод GetStringOrNullProperty(«AnswerSystemDataType»).

    • MethodType - содержит тип метода (Get/Post/Put/Delete). Получение значения осуществляется через метод GetStringOrNullPropert(«MethodType»).

    • MethodId - идентификатор вызванного обработчика. Можно получить с помощью метода коллекции свойства GetGuidProperty(«MethodId»).

    • Прочие свойства сообщения содержат все параметры, указанные на вкладке Параметры обработчика, если они есть.

Работа с массивами

Если на вкладке Ответ установлена переменная-массив, а в ответном сообщении пришел не массив, то:

  • пустое тело интерпретируется как пустой массив;

  • непустое тело интерпретируется как массив из 1го элемента.

Если на вкладке Ответ установлена переменная-не массив, а пришел массив, то:

  • пустой массив интерпретируется как пустое тело ответа; •массив из 1

    элемента интерпретируется как тело ответа; •массив из более 1 элемента интерпретируется как ошибка.

Коды ответных сообщений для веб-системы

Задать код ошибки для отправки сообщения об ошибке обработки в веб-адаптер:

ВхСообщ.SetProperty(«ResponseCode», «405»); ВхСообщ.SetProperty(«ResponseMessage», «Ошибка 405»);

Для веб-системы обрабатываются коды от 400 до 499, остальные коды возвращают 200 с записью в лог:

2020-08-17 10:29:26,537 [30] WARNING WebServiceExecutor - В ответе на сообщение для метода 0b00fd8e-c279-48af-9467-452784458540 ,corrId = 9ee2831e-b295-4e81-bf92-bf5d580894bd получен неверный код результата обработки 500

К о д

Название

Описание

2 0 0

ОК

Указывает, что запрос выполнен успешно и что запрошенная информация содержится в ответе

2 0 2

Accepted

Указывает, что запрос получен, но еще не обработан.

4 0 0

Bad Request

Указывает, что запрос не может быть понят сервером. Отправляется, когда никакая другая ошибка не применима, или если точная ошибка неизвестна или не имеет собственного кода ошибки.

4 0 1

U nauthorized

Указывает, что запрошенный ресурс требует аутентификации.

4 0 2

Payment Required

Предполагается использовать в будущем

4 0 3

Forbidden

Указывает, что сервер отказывается выполнить запрос.

4 0 4

Not Found

Указывает, что запрошенный ресурс не существует на сервере.

4 0 5

Method Not Allowed

Указывает, что метод запроса (POST или GET) не разрешен на запрашиваемом ресурсе.

4 0 6

Not Acceptable

Указывает, что клиент указал заголовками Accept, что он не будет принимать ни одно из доступных представлений ресурса.

4 0 7

Proxy Aut hentication Required

Указывает, что запрошенный прокси-сервер требует аутентификации.

4 0 8

Request Timeout

Указывает, что клиент не отправил запрос в течение ожидаемого сервером времени

4 0 9

Conflict

Указывает на то, что запрос не может быть выполнен из-за конфликтного обращения к ресурсу.

4 1 0

Gone

Указывает на то, что запрошенный ресурс больше не доступен.

4 1 1

Length Required

Указывает, что отсутствует заголовок требуемой длины.

4 1 2

P recondition Failed

Указывает, что условие, установленное для этого запроса, не выполнено, и запрос не может быть выполнен.

4 1 3

Payload Too Large

Указывает, что запрос является слишком большим для того, чтобы сервер его обработал.

4 1 4

URI Too Long.

Указывает, что URI слишком длинный.

4 1 5

Unsupported Media Type

Указывает, что запрос является неподдерживаемым типом.

4 1 6

Range Not Satisfiable

Указывает, что диапазон данных, запрошенных из ресурса, не может быть возвращен, либо потому что начало диапазона находится перед началом ресурса, либо конец диапазона находится после конца ресурса.

4 1 7

Expectation Failed

Указывает, что по каким-то причинам сервер не может удовлетворить значению поля Expect заголовка запроса.

4 1 8

I’m a teapot

4 1 9

Aut hentication Timeout

Используется в качестве альтернативы коду 401, которые прошли проверку подлинности, но лишены доступа к определенным ресурсам сервера

4 2 1

Misdirected Request

Указывает, что запрос был перенаправлен на сервер, не способный дать ответ

4 2 2

Un processable Entity

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

4 2 3

Locked

Указывает, что целевой ресурс из запроса заблокирован от применения к нему указанного метода

4 2 4

Failed Dependency

Указывает, что реализация текущего запроса может зависеть от успешности выполнения другой операции. Если она не выполнена и из-за этого нельзя выполнить текущий запрос, то сервер вернёт этот код

4 2 6

Upgrade Required

Указывает, что клиент должен переключиться на другой протокол

4 2 8

P recondition Required

Сервер указывает клиенту на необходимость использования в запросе заголовков условий

4 2 9

Too Many Requests

Указывает, что клиент попытался отправить слишком много запросов за короткое время

4 3 1

Request Header Fields Too Large

Указывает, что превышена допустимая длина заголовков

4 5 1

Unavailable For Legal Reasons

Указывает, что доступ к ресурсу закрыт по юридическим причинам

5 0 3

Service unavailable

Указывает на то, что сервер не готов обработать данный запрос.

Если код отсутствует в таблице, то возвращается ошибка без описания.

Описание веб-обработчиков находится в разделе Веб-обработчики.