Обработчик расширенного REST API

Веб-обработчик относится к системе, имеющей коннектор типа Расширенное REST API.

Внутри обработчика происходит настройка метода:

Наименование.
Комментарий.
Тип (Веб-обработчик).
Тип метода (GET, POST, PUT, DELETE).
Имя таблицы обработчика, которая будет выступать как источник, если указано направление В Platform. Если указано направление ИЗ Platform, таблица выступает как приемник.
Тип внешнего типа данных.
Шаблон пути. В поле Шаблон пути можно использовать параметры:
- {path} путь к методу со всей иерархией папок;
- {method} имя метода;
- {folder} имя текущей папки метода.
Таймаут вызова.
Параметры запроса.
вPlatform (для методов POST, PUT).
изPlatform (для методов POST, PUT).
Системы (список систем для данного обработчика).
Настройка флагов: требуется авторизация авторизация, ожидание ответа.

Если в Ответе настроен Немассив, а в теле сообщения от процесса приходит массив, при парсинге ответа в веб-сервис проверяется количество элементов в массиве:

если элементов 0, то это интерпретируется как пустое тело, выводится значение соответствующего типа данных с пустыми значениями полей;
если 1, то интерпретируется первый элемент массива как тело сообщения и выводится соответствующее значение;
в других случаях регистрируется ошибка, что получен массив.

Сообщения могут быть отправлены без указания в теле значений полей. Например:

{
  "поле3": "string"
}

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

 {
  "Поле1": "",
  "Поле2": null,
  "Поле3": "string"
}

Код обработчика

Код обработчика пишется на языке C#.

В коде обработчика c направлением В Platform доступна переменная RunMessage. В этой переменной содержится сообщение, полученное из внешней системы.

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

RunMessage.SetBody(Object); - установить новое тело сообщения.

API валидация

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

Примечание

При настроенном responseErrorSettings ошибки авторизации и отправки на узел возвращаются в том же стандартизированном формате JSON, что и прочие валидационные ошибки.

Чтобы сработали настройки responseErrorSettings и при необходимости переопределить код/сообщение/список полей в ответе, обработчик выбрасывает ValidateParametersException.

ValidateParametersException: класс, наследованный от Exception. Используется, чтобы сообщить валидатору об ошибках входных данных, вернуть стандартизированную JSON-ошибку и при необходимости переопределения частей ответа.

Конструкторы:

ValidateParametersException (string): инициализирует новый экземпляр класса ValidateParametersException указанным сообщением об ошибке.

ValidateParametersException (integer, string): инициализирует новый экземпляр класса ValidateParametersException указанным кодом об ошибке и сообщением об ошибке.

ValidateParametersException (integer, NotValidFields, string): инициализирует новый экземпляр класса ValidateParametersException указанным кодом об ошибке, сообщением об ошибке и невалидными полями.

ValidateParametersException (NotValidFields, string): инициализирует новый экземпляр класса ValidateParametersException невалидными полями и сообщением об ошибке.

Свойства:

NotValidFields: невалидные поля.

ValidationErrorCode: код ошибки.

NotValidFields: класс-обертка для заполнения имен невалидных полей.

Конструкторы:

NotValidFields: инициализирует новый экземпляр класса NotValidFields.

NotValidFields (string): инициализирует новый экземпляр класса NotValidFields с заполненным полем.

Свойства:

Fields: список string.

Методы:

void Add (string): добавляет в список одно имя.

bool Remove (string name): удаляет из списка одно имя, если такое существует.

void AddRange (List<string>): добавляет список имен.

Для выбрасывания исключения, которое позволяет изменить ответ на API-запрос (переопределить части ответа, соответствующего описанию в responseErrorSettings, который отправился бы без переопределения):

throw new ValidateParametersException(литерал_или_переменная_инт_переопределяет_validationErrorCode, new NotValidFields(литерал_или_переменная_стринг_переопределяет_notValidFields), литерал_или_переменная_стринг_переопределяет_errorMessage);

в котором вместо

new NotValidFields(литерал_или_переменная_стринг_переопределяет_notValidFields)

можно использовать доступную в коде обработчика переменную-список NotValidFields, у которой есть метод Add (литерал_или_переменная_стринг)

NotValidFields.Add ("поле")

Также в коде обработчика доступна переменная ValidationErrorCode, которой присвоено значение validationErrorCode из значения responseErrorSettings.

Если не заполнены настройки responseErrorSettings, но вызывается ValidateParametersException:

Переопределяется код ответа в соответствии с первым параметром вызываемого ValidateParametersException.

Текст ответа остается в виде строки со значением из 3 параметра.

Второй параметр (NotValidFields) в этом случае не используется (игнорируется).

Особенности формирования шаблона пути

Имена переменных регистрозависимые; если регистр переменной и маски в пути совпадает, то в запрос передается значение параметра из swagger веб-сервиса:

Если регистр не совпадает, то в запросе остается имя параметра в скобках:

Помимо этого, при формировании шаблона пути можно использовать стандартные маски, такие как {path}, {method} и {folder}. Если в параметрах обработчика будут заданы пользовательские параметры с этими именами, то они считаются приоритетными и подставляются в шаблон пути: иначе эти параметры будут определены автоматически от расположения обработчика в иерархии папок: