Введение

Comindware Platform позволяет отправлять HTTP-запросы типов GET, POST, PUT, DELETE для взаимодействия с внешними системами.

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

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

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

• Имеется приложение для работы с клиентами и заказами.
• В приложении настроены шаблоны:
  • «Клиенты» — для хранения данных клиентов.
  • «Заказы» — для хранения сведений о заказах, полученных из внешней системы.
• Имеется внешняя система управления заказами, предоставляющая данные заказов по HTTP-запросу.
• Требуется настроить приложение так, чтобы пользователь мог открыть карточку клиента и нажать кнопку «Получить заказы».
• По нажатию кнопки Comindware Platform должен отправлять GET-запрос во внешнюю систему, получать список заказов выбранного клиента, создавать для каждого заказа запись в шаблоне «Заказы» и связывать её с текущей записью клиента.

• Путь для запроса данных заказов: http://<your-hostname>/api/orders

  Примечание

  В данной статье рассматривается настройка отправки GET-запросов на URL http://<your-hostname>/api.

  Во всех примерах подставьте реальный адрес своего сервера вместо <your-hostname>.

• Запрос содержит параметр clientName с идентификатором клиента.

• В ответ на запрос сервер возвращает JSON-ответ с массивом данных заказов следующего вида:

{ 
    "error": false, 
    "status": "ok", 
    "statusCode": 200, 
    "orders": [ 
        { 
            "orderID": 1, 
            "orderStatus": "Fulfilled", 
            "orderAmount": 1000 
        }, 
        { 
            "orderID": 2, 
            "orderStatus": "Canceled", 
            "orderAmount": 5000 
        }, 
        { 
            "orderID": 3, 
            "orderStatus": "New", 
            "orderAmount": 3500 
        } 
    ] 
} 

Порядок настройки

1. Настройте подключение типа «Отправка HTTP-запросов».
2. Настройте путь передачи данных типа «Отправка HTTP-запросов».
3. Настройте шаблон для записи полученных данных.
4. Настройте сценарий, который будет формировать и отправлять HTTP-запрос на сервер, создавать записи заказов по данным из ответа и связывать их с текущим клиентом с использованием настроенных подключения и пути передачи данных.

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

1. Откройте раздел «Администрирование» — «Подключения».

2. В меню «Создать» выберите пункт «Подключения REST и OData» — «Отправка HTTP-запросов».

   

3. Настройте подключение для отправки HTTP-запросов со следующими параметрами:

   • URI — http://<your-hostname>/api. Символ / в конце URI не требуется.
   • Формат данных — JSON. Также поддерживаются XML и простой текст, но здесь рассматривается обработка данных в формате JSON.

4. Остальные параметры подключения настройте в соответствии с используемым сервером. См. статью «Отправка HTTP-запросов. Настройка подключения».

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

1. Откройте раздел «Администрирование» — «Пути передачи данных».

2. В меню «Создать» выберите пункт «Подключения REST и OData» — «Отправка HTTP-запросов».

   

3. Настройте свойства пути передачи данных на следующих вкладках:

   • Основные свойства
   • Атрибуты сообщения
   • Интеграция

4. Сохраните путь передачи данных.

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

• Подключение — выберите ранее созданное подключение для отправки HTTP-запросов.
• Системное имя — введите системное имя пути передачи данных латинскими буквами.
• Отключить — установите этот флажок, если требуется деактивировать путь передачи данных.
• Описание — введите наглядное описание назначения пути передачи данных.

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

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

• Запрос — добавьте атрибут queryParams (произвольное системное имя, которое будет указано в поле «Атрибут для параметров запроса» на вкладке «Интеграция» и в действии сценария «Изменить значения переменных») типа «Объект».

  • Установите флажок «Массив».

  • Установите флажок у атрибута queryParams и добавьте его дочерние атрибуты:

    • name (предопределённое системное имя) типа «Строка» — этот атрибут будет содержать имена параметров запроса.
    • value (предопределённое системное имя) типа «Строка» — этот атрибут будет содержать значения параметров запроса.
    • Установите флажок «Массив» у атрибута value.

    В эти атрибуты будут передаваться пары ключ-значение параметров запроса.

• Ответ — добавьте атрибут с системным именем orders (совпадает с именем массива данных заказов в ответе сервера на HTTP-запрос) типа «Объект».

  • Установите флажок «Массив»
  • Установите флажок у атрибута orders и добавьте его дочерние атрибуты:
    • orderAmount (совпадает с именем параметра из ответа сервера) типа «Число» — этот атрибут будет содержать сумму заказа.
    • orderID  (совпадает с именем параметра из ответа сервера) типа «Число» — этот атрибут будет содержать ID заказа.
    • orderStatus (совпадает с именем параметра из ответа сервера) типа «Строка» — этот атрибут будет содержать статус заказа. В эти атрибуты будут записываться значения из ответа сервера на запрос.
• Ответ с ошибкой — настройте атрибуты для получения ответа сервера с ошибкой аналогично атрибутам запроса и ответа. Например, errorResponse типа «Строка».

Интеграция

• Метод запроса — выберите пункт «GET».
• Шаблон пути запроса — введите orders (фактический путь к HTTP-запросу на сервере), этот суффикс будет добавлен к URI, указанному в свойствах подключения для отправки HTTP-запросов. Например, для URI http://<your-hostname>/api результирующий путь запроса будет http://<your-hostname>/api/orders.
• Атрибут для сериализации в тело запроса — оставьте пустым, так как в данном примере используется метод GET без тела запроса.

• Атрибут для параметров запроса — введите системное имя атрибута из таблицы «Запрос» на вкладке «Атрибуты сообщений». В данном случае, введите queryParams.

  

• Атрибуты для десериализации ответа без ошибки и  Атрибуты для десериализации ответа с ошибкой

  • Создайте одну строку в каждой таблице и введите символ $ в столбцы «Путь к атрибуту» и «Выражение на языке запросов».

    

Настройка шаблона записи

1. Создайте шаблон записи «Заказы» со следующими атрибутами:

   Системное имя	Тип	Параметры
   «ID_заказа»	Число	Установить флажок «Использовать как заголовок записей»
   «Статус»	Текст
   «Сумма_заказа»	Число	Количество знаков после запятой: «Не преобразовывать»

2. Создайте шаблон записи «Клиенты».

3. Добавьте следующие атрибуты:

   Системное имя	Тип	Параметры
   «Название»	Текст	Установить флажок «Использовать как заголовок записей»
   «Заказы»	Запись	(«Хранить несколько значений») связанный с шаблоном «Заказы» с атрибутом «Клиент»

4. Добавьте кнопку «Получить заказы» со следующими свойствами:

   • Контекст операции: запись
   • Операция: вызвать событие «Нажата кнопка»
   • Результат выполнения: обновить данные

5. Поместите атрибуты и кнопку на основную форму. Представление атрибута «Заказы» сделайте в виде таблицы и вынесите на неё атрибуты «ID заказа», «Статус» и «Сумма заказа».

Настройка сценария отправки HTTP-запроса

1. Создайте сценарий, выполняющийся по нажатию кнопки. Выберите в настройках блока контекстный шаблон записи и кнопку (например, контекстный шаблон: Клиенты, кнопка: Получить заказы).

   

2. Добавьте и настройте действие «Изменить значения переменных».

   • Операция со значениями переменных — Заменить.
   • Набор переменных — queryParamsContainer (произвольное системное имя), из этого массива последующее действие «Отправить сообщение» передаст параметры в HTTP-запрос.

   • В таблице атрибутов создайте атрибут queryParams (это системное имя массива атрибутов запроса, указанное на вкладке «Атрибуты сообщений» в свойствах пути передачи данных), который будет содержать пару ключ-значение для параметра HTTP-запроса в двух дочерних атрибутах:

     • name — введите формулу с именем параметра HTTP-запроса (например, "clientName").

     • value — введите формулу, выражение на N3 или выберите атрибут с необходимым значением параметра HTTP-запроса (например, атрибут Имя).

       Примечание

       Чтобы передать в HTTP-запрос несколько параметров, создайте необходимое количество атрибутов с одинаковым системным именем и настройте их дочерние атрибуты, например для массива из двух элементов:

       • queryParams
         • name
         • value
       • queryParams
         • name
         • value

       

3. Добавьте и настройте действие «Отправить сообщение».

   • Подключение — выберите подключение для отправки HTTP-запросов.
   • Путь передачи данных — выберите ранее настроенный путь для передачи данных HTTP-запроса.
   • Переменная с сообщением — введите системное имя набора переменных, указанное в предшествующем действии «Изменить значения переменных» (например, queryParamsContainer).
   • Переменная для успешного ответа — введите системное имя переменной, в которую будет помещён ответ сервера на HTTP-запрос (например, response).

   • Переменная для ответа с ошибкой — введите системное имя переменной, в которую будет помещён ответ сервера в случае ошибки (например, errorResponse).

     

4. Добавьте и настройте действие «Повторять по количеству объектов».

   • Переменная — введите имя переменной, в которую будут помещены объекты, полученные из ответа на HTTP-запрос (например, loopiterator). Эта переменная будет использоваться для обращения к объектам в ответе от сервера в последующем действии «Изменить значения атрибутов».

   • Атрибут или выражение для поиска объектов — введите формулу вида $$response->orders, где response — имя переменной для успешного ответа, указанное в свойствах действия «Отправить сообщение», orders — системное имя атрибута ответа, указанное на вкладке «Атрибуты сообщений» в свойствах пути передачи данных.

     

5. Внутри действия «Повторять по количеству объектов» добавьте действие «Создать запись».

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

   

7. На вкладке «Основные»:

   • Целевой шаблон записи — выберите шаблон записи Заказы.
   • Ссылка на новую запись — выберите атрибут типа «Запись» Заказы.
   • Операция со значениями — выберите операцию Добавить.

8. Внутри действия «Создать запись» добавьте действие «Изменить значения атрибутов».

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

10. На вкладке «Основные»:

    • В таблице атрибутов добавьте атрибуты, значения которых следует заполнить из полученного ответа от сервера.

    • В столбце «Значение» для каждого атрибута введите формулу вида $$loopiterator->objectName, где loopiterator — имя переменной, заданное в действии «Повторять по количеству объектов», а objectName — имя атрибута ответа, заданное в атрибутах сообщений при настройке пути передачи данных (см. Настройка пути передачи данных - Атрибуты сообщений).

      

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

    

12. Проверьте работу приложения: сценарий должен отправлять HTTP-запрос и записывать данные из ответа сервера в атрибуты шаблона.