HTTP-запросы. Получение JSON-данных. Настройка подключения, пути передачи данных и сценария

Введение

Comindware Platform может получать и обрабатывать HTTP-запросы из внешних систем.

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

Настройка для обработки XML и простого текста будет аналогичной.

Логика обработки входящих HTTP-запросов

Для получения HTTP-запросов из внешних систем Comindware Platform позволяет настроить конечные точки API вида:
https://<instanceUrl>/api/public/adapter/<connectionUri>/<routeUri>
Здесь:
- <instanceUrl> — адрес экземпляра Comindware Platform;
- <connectionUri> — путь URI, настроенный в свойствах подключения для получения HTTP-запросов;
- <routeUri> — путь URI, настроенный в свойствах пути передачи данных для получения HTTP-запросов.
При поступлении HTTP-запроса на настроенную конечную точку Comindware Platform запускает сценарий по событию «Получение сообщения» и передаёт в него данные запроса.

Аутентификация для доступа к Comindware Platform по HTTP

Для базовой аутентификации при отправке HTTP-запросов в Comindware Platform следует использовать учётные данные аккаунта, который имеет разрешение на вызовы API. По умолчанию такое разрешение имеют аккаунты с системной ролью «Системные администраторы».

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

См. также «HTTP-запросы с составным содержимым. Получение файлов в сценарии»

Прикладная задача

Имеется шаблон записи «Заказы», с атрибутами:
- Номер типа «Число»
- Клиент типа «Текст»
- Товар типа «Текст»

Внешний сервер отправляет в Comindware Platform HTTP-запросы с данными в формате JSON следующего вида:

{ 
    "ListZakazov":[ 
        { 
            "Zakaz":{ 
                "Client": "STRING", 
                "Nomer": "NUMBER", 
                "Tovar": "STRING" 
            } 
        } 
    ] 
} 

Требуется настроить получение c внешнего сервера HTTP-запросов с данными заказов.
При получении HTTP-запроса требуется создать запись в шаблоне «Заказы» и заполнить её полученными данными.

Примечание

Здесь не рассматривается проверка полученных данных на уникальность и совпадение с имеющимися в записях.

Порядок настройки получения HTTP-запросов

Настройте подключение для получения HTTP-запросов.
Настройте путь передачи данных для получения HTTP-запросов.
Настройте сценарий для обработки входящих HTTP-запросов.
Проверьте работоспособность настроенной конфигурации.

Настройка подключения

На странице «Администрирование» выберите пункт «Инфраструктура» — «Подключения» .
Откройте или создайте подключение типа «Подключения REST и OData» — «Получение HTTP-запросов».
Настройте подключение к серверу:
- Системное имя — введите уникальное имя подключения. Не должно начинаться с цифры. Разрешены английские и русские буквы, цифры и символ «_». Рекомендуется использовать английские буквы.
- Отключить — установите этот флажок, если требуется временно деактивировать данное подключение.
- Описание — введите наглядное описание подключения, например «Подключение для получения заказов HTTP».
- Запись в файловые журналы — выберите, какие события следует записывать в журналы:
  - Полные сведения об обработке сообщения;
  - Только ошибки;
  - Отключить — не регистрировать в журнале события получения запросов.
- Базовый путь получения HTTP-запросов — добавьте путь URI, например uploadData. При необходимости введите дополнительный путь URI на вкладке «Интеграция» в свойствах пути передачи данных. Укажите результирующий путь на внешнем сервере в качестве получателя запроса, например:
  https://<hostname>/api/public/adapter/uploadData
- Формат данных — выберите представление данных:
  - JSON — используется в данном примере;
  - XML;
  - Простой текст.
- Тип аутентификации — выберите способ проверки подлинности, используемый сервером:
  - Отсутствует;
  - Базовая;
  - Аутентификация Windows.
Сохраните подключение.

Настройка пути передачи данных

Откройте страницу «Администрирование» — «Архитектура» или страницу «Администрирование» приложения.
Выберите пункт «Пути передачи данных» .
Откройте или создайте путь передачи данных типа «Подключения REST и OData» — «Получение HTTP-запросов».
Настройте свойства пути передачи данных на следующих вкладках:
Сохраните путь передачи данных.

Основные свойства

На вкладке «Основные свойства» настройте параметры использования пути передачи данных:

Подключение — выберите подключение для получения HTTP-запросов.
Системное имя — введите уникальное имя пути передачи данных. Не должно начинаться с цифры. Разрешены английские и русские буквы, цифры и символ «_». Рекомендуется использовать английские буквы.
Отключить — установите этот флажок, если требуется временно деактивировать путь передачи данных.
Описание — введите наглядное описание пути передачи данных, например «Получение заказов по HTTP».
Номер шины данных — выберите номер от 0 до 3, если требуется распределить потоки данных нескольких путей для повышения производительности.

Атрибуты сообщений

Составление атрибута сообщения типа «Объект»

Чтобы составить атрибут сообщения типа «Объект» для хранения структурированных данных, необходимо создать структуру из родительского и дочерних атрибутов:

Создайте атрибут типа «Объект», задайте его имя, но оставьте значение пустым.
Установите флажок у имени родительского атрибута в таблице и нажмите кнопку «Добавить».
Дважды нажмите значок рядом с родительским атрибутом.
В таблице отобразится строка дочернего атрибута.
Задайте системное имя и тип дочернего атрибута.

Выберите тип сообщения «Обработка HTTP-запросов».

В таблице «Запрос» сопоставьте данные HTTP-запроса с атрибутами Comindware Platform, то есть воссоздайте структуру JSON входящего запроса:

В таблицу «Запрос» добавьте атрибут ListZakazov типа «Объект». Установите флажок «Массив», так как этот атрибут будет содержать массив данных по всем заказам. Системное имя должно совпадать с именем соответствующего поля HTTP-запроса.
В атрибут FileObject добавьте дочерний атрибут Zakaz типа «Объект». Он будет содержать данные по одному заказу.
В атрибут Zakaz добавьте следующие дочерние атрибуты:

Системное имя	Тип	Описание
Nomer	Число	Номер заказа
Client	Строка	Название клиента
Tovar	Строка	Название товара

Системные имена этих атрибутов должны совпадать с именами соответствующих полей HTTP-запроса.

При необходимости настройте ответ — здесь можно составить структуру JSON, которая будет отправляться в ответе на запрос после его успешной обработки, и ответ с ошибкой — структуру JSON для ответа на запрос, при обработке которого произошла ошибка.

Интеграция

При необходимости укажите дополнительный суффикс в поле «Путь URI». Этот суффикс будет добавлен к URL-адресу в поле «Базовый путь получения HTTP-запросов» (совпадает с путём, настроенным в подключении). Укажите результирующий адрес на внешнем сервере в качестве получателя запросов, например:
https://<hostname>/api/public/adapter/uploadData
Укажите атрибуты для десериализации данных. По умолчанию следует указать $ в обоих столбцах, чтобы получить всю структуру JSON из запроса. Для поиска определенного атрибута используйте JSONPath.
При необходимости укажите атрибут для заголовков, в котором будут содержаться все атрибуты заголовков запроса, атрибут для параметров запроса, в котором будут содержаться все параметры запроса, и атрибут для тела запроса, в котором будет содержаться всё тело запроса.

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

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

Создайте новый сценарий «Обработка заказов».
У начального события измените тип на «Получение сообщения» и настройте его:
- Контекстный шаблон: Заказы
- Подключение: подключение для получения HTTP-запросов
- Путь передачи данных: путь передачи данных для получения HTTP-запросов
- Имя переменной: Request

Добавьте действие «Повторять по количеству объектов» со следующими свойствами:

Имя переменной: local

Атрибут или выражение для поиска объектов: N3

# Импортируем функции для работы 
# с данными текущего сеанса и переменными 
@prefix session: <http://comindware.com/ontology/session#>. 
@prefix var: <http://comindware.com/ontology/session/variable#>. 
{ 
    # Request — переменная из первого блока,  
    # в которой находится разобранный JSON 
    session:context var:Request ?req. 
    # ListZakazov - переменная,  
    # в которой находится массив объектов 
    ?req var:ListZakazov ?value. 
} 

Внутрь действия «Повторять по количеству объектов» добавьте действие «Создать запись» и укажите шаблон записи «Заказы».
Внутрь действия «Создать запись» добавьте действие «Изменить значения атрибутов».
В действии «Изменить значения атрибутов» на вкладке «Дополнительно» установите флажок «Сбрасывать кэш значений».

На вкладке «Основные» настройте следующие атрибуты:

Атрибут	Операция со значениями	Значение
Клиент	Заменить	Формула: `$$local—Zakaz—Client`
Номер	Заменить	Формула: `$$local—Zakaz—Nomer`
Товар	Заменить	Формула: `$$local—Zakaz—Tovar`

Примечание

Переменная $$local — хранит значение текущего объекта итерации. Пример:

{ 
    "Zakaz":{ 
        "Client": "Петров", 
        "Nomer": 54, 
        "Tovar": "Яблоко" 
    } 
} 

Переменная $$local—>Zakaz содержит данные заказа из текущего объекта итерации. Пример:

{ 
    "Client": "Петров", 
    "Nomer": 54, 
    "Tovar": "Яблоко" 
} 

Переменная $$local—>Zakaz—>Tovar содержит данные о товаре по заказу из текущего объекта итерации. Пример:

"Яблоко"

Получившийся сценарий должен выглядеть следующим образом:

Сценарий обработки заказа

Тестирование

С внешнего сервера отправьте в Comindware Platform запрос с данными заказов, например:

curl -X POST \ 
    -u username:password \ 
    -H "Content-Type: application/json" \ 
    -d '{ 
        "ListZakazov": [ 
            { 
                "Zakaz": { 
                    "Client": "Петров", 
                    "Nomer": 54, 
                    "Tovar": "Яблоко" 
                } 
            }, 
            { 
                "Zakaz": { 
                    "Client": "Иванов", 
                    "Nomer": 60, 
                    "Tovar": "Банан" 
                } 
            }, 
            { 
                "Zakaz": { 
                    "Client": "Сидоров", 
                    "Nomer": 61, 
                    "Tovar": "Груша" 
                } 
            } 
        ] 
    }' \ 
    https://<hostname>/api/public/adapter/uploadData 
    - v 

Здесь:

-X POST — метод запроса (необязательный ключ);
-u username:password — базовая аутентификация c учётными данными аккаунта с разрешением на вызовы API Comindware Platform;
-H "Content-Type: application/json" — заголовок, указывающий на формат данных JSON;
-d '...' — тело запроса с JSON-структурой;
https://<hostname>/api/public/adapter/uploadData — базовый путь получения HTTP-запросов и путь URI, настроенные в пути передачи данных;
-v — вывод отладочных данных (необязательный ключ).

Проверьте обработку запроса: должны быть созданы записи в шаблоне «Заказы», соответствующие полученному запросу, как показано на иллюстрации: