Расширенное REST API

Внешняя система предназначена для подключения к системе собственного веб-сервера с наборами веб-методов и описанием типов.

Основные настройки

Чтобы приступить к настройке внешней системы, на вкладке Коннектор выберите тип Расширенное REST API. После выбора типа коннектора станут доступны поля для ввода характеристик внешней системы:

../../_images/image94.png

Для публикации API следует указать порт веб-сервера. Флажок Использовать https устанавливается при использовании защищенного протокола передачи данных.

Настройка аутентификации

При использовании аутентификации для работы внешней системы установите флажок Требовать авторизацию. Для аутентификации в системе используются учетные данные внутренних пользователей, созданных в сервисе Управление пользователями. При этом привязка внутренних пользователей к конкретным внешним системам отсутствует, аутентификация возможна при использовании учетных данных любого внутреннего пользователя. Настройка параметров аутентификации производится в режиме редактирования конфигурации.

Для включения аутентификации в системе установите значение true в значении ключа enabled (тип boolean), который находится в значении ключа auth (тип object).

Также в значении ключа authTypeRest (тип string), который находится в значении ключа asServer (тип object), установите тип аутентификации с возможными значениями:

  • Basic: базовый тип аутентификации.

  • Bearer: аутентификация с использованием токена на предъявителя Bearer (используется по умолчанию).

Пример части конфигурации внешней системы с настройками для включения аутентификации в системе:

{
  "$type": "DT.ClusterConfiguration.DtSystem, DT_Core",
  "config": {
        "$type": "DT.ConfigurationRepository.Configuration.Adapter.WebSystemSimpleConfig, DT_ConfigurationRepository",
        "asServer": {
          "$type": "DT.ConfigurationRepository.Configuration.Adapter.WebServerConfig, DT_ConfigurationRepository",
          "authTypeRest": "Bearer"
          "credentialsInBody": true
        },
        "auth": {
          "$type": "DT.ClusterConfiguration.AuthenticationConfig, DT_Core",
          "enabled": true,
          "usePasswordHash": false
        }
  }
}

При значении «usePasswordHash: true» для аутентификации требуется передавать не сам пароль, а только хеш от него (SHA256 в шестнадцатеричном формате).

Basic (базовый тип)

При включении аутентификации с типом Basic в API-запросах работы с внешней системой должен добавляться заголовок Authorization, содержащий необходимые аутентификационные данные в соответствии со стандартом аутентификации Basic.

Bearer

При включении аутентификации с типом Bearer к API-запросам работы с внешней системой добавляется запрос получения токена Bearer (токен должен быть использован при выполнении остальных запросов работы с внешней системой) и запрос отмены токена:

  • POST запрос /api/session/token, в котором представлены параметры логина и пароля внутреннего пользователя для получения токена Bearer, который затем должен добавиться в заголовок Authorization в API-запросах работы со внешней системой; значение токена хранится в поле AccessToken json-ответа на запрос.

  • POST запрос /api/session/logout для отмены выданного токена.

    Если в настройках сервиса Управление пользователями в значении поля tokenIsUpdatable указано значение true, поле RefreshToken json-ответа на POST запрос /api/session/token хранит значение токена (поле RefreshToken) для обновления токена авторизации AccessToken (если tokenIsUpdatable = false, в RefreshToken возвращается null), при обновлении токена авторизации сохраняется сессия (SessionId). Также к API-запросам работы с внешней системой добавляется PUT запрос /api/session/token, с помощью которого можно обновить AccessToken.

Все возможности и параметры API-запросов работы со внешней системой, которые добавляются при включении аутентификации, доступны в Swagger, который запускается после создания внешней системы. Адрес Swagger доступен на странице внешней системы в ЦМ:

../../_images/sw_rest.png

Для авторизации в Swagger системы получите актуальный токен с помощью POST запроса /api/session/token, введите значение Bearer и через пробел значение полученного токена в окне Available authorizations и нажмите на кнопку Authorize.

../../_images/rest_swagger_auth.png

Передача аутентификационных данных в запросе получения токена Bearer

При аутентификации с типом Bearer выбор способа передачи аутентификационных данных в запросе получения токена Bearer (логин и пароль) осуществляется с помощью параметра credentialsInBody.

При значении credentialsInBody: true в запросе получения токена Bearer для аутентификации имя пользователя и пароль внутреннего пользователя будут переданы в теле запроса, при значении false - в параметрах запроса. Значение по умолчанию - true.

В swagger внешней системы при значении credentialsInBody: true отображается следующая информация:

../../_images/rest_swagger_auth_true.png

Пример команды curl для отправки запроса при значении параметра true:

curl --location 'http://example:8302/api/session/token' \
--header 'Content-Type: application/json' \
--data '{
  "login": "example_name",
  "password": "example_name1"
}'

В swagger внешней системы при значении credentialsInBody: false отображается следующая информация:

../../_images/rest_swagger_auth_false.png

Пример команды curl для отправки запроса при значении параметра false:

curl --location --request POST 'http://example:8302/api/session/token?login=example_name&password=example_name1'

Редактирование конфигурации

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

../../_images/image802.png

Внимание

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

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

В блоке config следует указать необходимый тип конфигурации адаптера.

Все актуальные примеры настроек можно взять из Swagger ЦН, контроллер XampleSystemConfig GET/examples/adapters/web Web Адаптер.

В режиме конфигурации настраиваются следующие параметры:

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

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

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

    Примечание

    Изменение этого параметра не приводит к перезагрузке расширенного REST API и не влечет за собой перенагрузку системы.

  • auth - настройки аутентификации для обработчиков с установленным флагом Требуется авторизация.

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

  • sslProtocols - параметр настройки протоколов SSL. Поддерживается работа со следующими протоколами: TLS1.0, TLS1.1, TLS1.2. Доступны к использованию только протоколы, указанные в параметрах TLS при запросах к системе. Настройка протокола учитывается только при значении true параметра useHttps. Актуальные настройки SSL отображаются в ЦМ:

    ../../_images/ssl_cm.png

    Примечание

    Если значения параметра не указаны, будут использованы настройки по умолчанию (разрешено использование всех поддерживаемых протоколов), при этом информация о выбранных протоколах не будет отображаться в ЦМ.

Пример конфигурации внешней системы:

{
        "$type": "DT.ClusterConfiguration.DtSystem, DT_Core",
        "config": {
                "$type": "DT.ConfigurationRepository.Configuration.Adapter.WebSystemConfig, DT_ConfigurationRepository",
                "connectorType": "Web",
                "port": 102,
                "useHttps": true,
                "replyStoreTime": 0,
                "publishSwagger": true,
                "authTypeRest": "Bearer",
                "sslProtocols": [
                                "Tls",
                                "Tls11",
                                "Tls12"
                        ],
                "auth": {
                        "$type": "DT.ClusterConfiguration.AuthenticationConfig, DT_Core",
                        "enabled": true,
                        "usePasswordHash": false
                },
                "handlersList": [],
                "sendingStrategy": ""
        },
        "isActive": true,
        "folderId": null,
        "servers": [
                ""
        ],
        "entityId": "1ee43391-769d-417b-a9d6-d9476632ea0d",
        "clusterId": "2f070fd4-ccba-4c25-bfd9-334c4a5f64a6",
        "name": "REST",
        "description": "Test",
        "version": 1,
        "tagsCollection": [],
        "className": "System",
        "classNameStr": "Внешняя система"
}

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

После внесения данных нажмите на кнопку Сохранить, после этого нажмите на кнопку Применить конфигурацию:

../../_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

Код

Название

Описание

200

ОК

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

202

Accepted

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

400

Bad Request

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

401

Unauthorized

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

402

Payment Required

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

403

Forbidden

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

404

Not Found

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

405

Method Not Allowed

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

406

Not Acceptable

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

407

Proxy Authentication Required

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

408

Request Timeout

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

409

Conflict

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

410

Gone

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

411

Length Required

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

412

Precondition Failed

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

413

Payload Too Large

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

414

URI Too Long

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

415

Unsupported Media Type

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

416

Range Not Satisfiable

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

417

Expectation Failed

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

418

I’m a teapot

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

419

Authentication Timeout

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

421

Misdirected Request

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

422

Unprocessable Entity

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

423

Locked

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

424

Failed Dependency

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

426

Upgrade Required

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

428

Precondition Required

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

429

Too Many Requests

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

431

Request Header Fields Too Large

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

451

Unavailable For Legal Reasons

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

503

Service unavailable

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

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

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

Мониторинг

В Журнале ЦМ отображается информация о запросах, выполненных с ошибкой:

../../_images/monitoring_log1.png

В Событиях есть возможность сохранять (логировать) заголовки из сообщений. Заголовки отображаются в поле Детали:

../../_images/monitoring_log2.png