HTTP-запросы типа POST. Отправка составного содержимого и файлов. Настройка подключения, пути передачи данных и сценария

Введение

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

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

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

Имеется шаблон «Реестр документов», содержащий записи с прикреплёнными файлами.

Требуется настроить кнопку для отправки прикреплённых файлов во внешнюю систему с помощью HTTP-запроса типа POST.

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

1. На странице Администрирование» выберите пункт «Инфраструктура» — «Подключения» ‌.
2. Откройте или создайте подключение типа «Подключения REST и OData» — «Отправка HTTP-запросов».

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

   • Системное имя — введите уникальное имя подключения. Не должно начинаться с цифры. Разрешены английские и русские буквы, цифры и символ «_». Рекомендуется использовать английские буквы.
   • Отключить — установите этот флажок, если требуется временно деактивировать данное подключение.
   • Описание — введите наглядное описание подключения, например «Подключение для отправки HTTP-запросов».
   • Запись в файловые журналы — выберите, какие события следует записывать в журналы:
     • Полные сведения об обработке сообщения;
     • Только ошибки;
     • Отключить — не регистрировать в журнале события отправки запросов.
   • URI — введите URL-адрес сервера, принимающего HTTP-запросы, например http://example.com/api. Символ / в конце URL не требуется.
   • Формат данных — выберите представление данных:
     • JSON — используется в данном примере;
     • XML;
     • Простой текст.
   • Кодировка данных — укажите формат кодировки данных, используемый сервером, по умолчанию: UTF-8.
   • Тип аутентификации — выберите способ проверки подлинности, используемый сервером:
     • Отсутствует;
     • Базовая;
     • Аутентификация Windows.
   • Имя пользователя — укажите учётную запись для подключения к серверу.
   • Пароль — введите пароль к учётной записи для подключения к серверу.
   • Домен — укажите домен пользователя сервера.

4. Проверьте соединение с сервером, нажав соответствующую кнопку.

5. При необходимости нажмите кнопку «Скачать журнал», чтобы просмотреть журнал событий отправки запросов.
6. Сохраните подключение.

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

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

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

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

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

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

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

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

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

1. Выберите тип сообщения «Отправка HTTP-запросов с составным содержимым» или «Отправка HTTP-запросов».
2. В таблицу «Запрос» добавьте атрибут типа «Объект», например File.

3. Добавьте дочерние атрибуты name и content типа «Строка».

   Внимание!

   Системные имена атрибутов сообщения для передачи имени и содержимого файла должны быть обязательно name и content строчными буквами.

Интеграция

• Если на вкладке «Атрибуты сообщений» выбран тип сообщения «Отправка HTTP-запросов с составным содержимым», настройте параметры на вкладке «Интеграция» следующим образом:

  1. Выберите метод запроса POST.
  2. В таблицу «Атрибуты для формирования тела запроса (POST, PUT)» добавьте атрибут File с форматом данных «Файловая структура».

• Если на вкладке «Атрибуты сообщений» выбран тип сообщения «Отправка HTTP-запросов», настройте параметры на вкладке «Интеграция» следующим образом:

  1. Выберите метод запроса POST.
  2. В поле «Атрибуты для сериализации в тело запроса» укажите File.

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

1. Создайте шаблон записи «Реестр документов» с системным именем DocumentRegistry.

2. Создайте атрибут «Вложения»:

   • Тип данных: документ
   • Системное имя: Attachment
   • Хранить несколько значений: флажок установлен

3. Создайте кнопку «Отправить вложения» со следующими свойствами:

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

4. Поместите атрибут «Вложения» и кнопку «Отправить вложения» на форму.

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

1. Создайте сценарий «Отправка документов через HTTP».
2. В свойствах события «Нажатие кнопки» выберите контекстный шаблон «Реестр документов» и кнопку «Отправить вложения».

3. После события «Нажатие кнопки» создайте действие «Повторять по количеству объектов» со следующими свойствами:

   • Объект для поиска: атрибут «Вложения»

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

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

     • Сообщение об ошибке: Ошибка отправки вложения

     • Выражение: N3

       # Импортируем функции для работы с данными текущего сеанса и переменными 
       @prefix object: <http://comindware.com/ontology/object#>. 
       @prefix document: <http://comindware.com/ontology/document#>. 
       @prefix operator: <http://comindware.com/ontology/session/operator#>. 
       @prefix variable: <http://comindware.com/ontology/session/variable#>. 
        
       { 
           # Находим атрибут Attachment (Вложение)  
           # в шаблоне DocumentRegistry (Реестр документов). 
           ("DocumentRegistry" "Attachment") object:findProperty ?Attachment. 
           # Помещаем объект с файлом из ?Attachment в ?AttachmentItem. 
           ?item ?Attachment ?AttachmentItem. 
           # Помещаем содержимое файла из ?AttachmentItem в ?content. 
           ?AttachmentItem document:content ?content. 
           # Помещаем имя файла из ?AttachmentItem в ?name. 
           ?AttachmentItem document:title ?name. 
           # Создаём в сценарии переменную content и помещаем в неё ?content 
           variable:content operator:replace ?content. 
           # Создаём в сценарии переменную name и помещаем в неё ?name 
           variable:name operator:replace ?name. 
           true -> ?value. 
       } 
       

   • На вкладке «Дополнительно»:

     • Сбрасывать кэш значений: флажок установлен

5. Внутрь действия «Повторять по количеству объектов» добавьте действие «Изменить значения переменных» со следующими свойствами:

   • На вкладке «Основные»:
     • Операция со значениями переменных: заменить
     • Набор переменных: Message
   • На вкладке «Дополнительно»:
     • Сбрасывать кэш значений: флажок установлен

6. В действии «Изменить значение переменных» на вкладке «Основные» добавьте переменные:

   Сопоставление переменных и объектов с атрибутами сообщения

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

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

   Имена переменных, значения которых передаются в атрибуты сообщений с помощью действия сценария «Отправить сообщение», должны совпадать с системными именами атрибутов сообщения.

   • File — с дочерними переменными:

     • content — значение: формула

     $$content 
     

     • name — значение: формула

     $$name 
     

     Здесь $$content и $$name — переменные, которые были созданы на шаге 4.

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

   • На вкладке «Основные»:
     • Подключение: выберите подключение для отправки файлов по HTTP.
     • Путь передачи данных: выберите путь передачи данных для отправки файлов по HTTP.
     • Переменная с сообщением: Message
   • На вкладке «Дополнительно»:
     • Сбрасывать кэш значений: флажок установлен

8. Внутрь действия «Повторять по количеству объектов» добавьте действие «Проверить результат выражения» со следующими свойствами:

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

     • Сообщение об ошибке: Ошибка очистки переменных

     • Выражение: N3

       # Импортируем функции для работы с переменными 
       @prefix variable: <http://comindware.com/ontology/session/variable#>. 
       @prefix operator: <http://comindware.com/ontology/session/operator#>. 
       { 
           # Очищаем переменную Message 
           variable:Message operator:clear ?item. 
           # Возвращаем значение true 
           true -> ?value. 
       } 
       

   • На вкладке «Дополнительно»:

     • Сбрасывать кэш значений: флажок установлен

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

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