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

Введение

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

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

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

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

• Имеется шаблон записи «Картотека».
• К каждой записи в Картотеке можно прикрепить несколько файлов и добавить описание.

• Имеется внешний сервер, отправляющий HTTP-запросы в формате multipart/form-data с файлами вида:

  { 
  "description": "STRING", 
  "files":[ 
       { 
          "name": "STRING", 
          "content": "STRING" 
      } 
  ] 
  } 
  

• Требуется настроить получение с внешнего сервера HTTP-запросов с файлами.

• При получении HTTP-запроса требуется создать запись в Картотеке, прикрепить к ней полученные файлы и заполнить Описание.

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

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

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

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

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

2. Поместите атрибуты «Файлы» и «Описание» на форму.

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

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

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

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

   • Базовый путь получения HTTP-запросов — добавьте путь URI, например httpListener. При необходимости введите дополнительный путь URI на вкладке «Интеграция» в свойствах пути передачи данных. Укажите результирующий путь на внешнем сервере в качестве получателя запроса, например:

     https://<hostname>/api/public/adapter/httpListener 
     

   • Формат данных — выберите представление данных:

     • JSON — используется в данном примере;
     • XML;
     • Простой текст.
   • Тип аутентификации — выберите способ проверки подлинности, используемый сервером:
     • Отсутствует;
     • Базовая;
     • Аутентификация Windows.

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

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

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

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

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

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

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

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

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

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

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

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

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

   Внимание!

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

4. На верхнем уровне таблицы «Запрос» добавьте атрибут Description типа «Строка».

Интеграция

1. Укажите дополнительный путь URI, например uploadFiles.

   Формирование адреса для входящих HTTP-запросов

   Путь URI с вкладки «Интеграция» будет добавлен к базовому пути получения HTTP-запросов (например, https://<hostname>/api/public/adapter/httpListener). Базовый путь настраивается в свойствах подключения.

   Укажите результирующий адрес на внешнем сервере в качестве получателя запросов, например:

   https://<hostname>/api/public/adapter/httpListener/uploadFiles 
   

2. В таблицу «Укажите атрибуты для преобразования составного содержимого запроса» сопоставьте атрибуты сообщения (Имя атрибута) с полями HTTP-запросов (Имя части составного содержимого):

   Имя атрибута	Имя части составного содержимого
   Description	description
   FileObject	files

3. В поле «Возвращаемый формат данных» укажите «Составное содержимое».

4. Остальные поля можно не заполнять.

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

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

2. Откройте событие «Нажатие кнопки» и настройте его следующим образом:

   • Тип: получение сообщения;
   • Контекстный шаблон: Картотека;
   • Подключение: подключение для получения документов с помощью HTTP-запросов;
   • Путь передачи данных: путь передачи данных для получения документов с помощью HTTP-запросов;
   • Имя переменной: HttpRequest — в эту переменную будет сохраняться полученный HTTP-запрос. Имя переменной может быть произвольным.

3. Добавьте действие «Создать запись» для контекстного шаблона «Картотека».

4. Добавьте действие «Изменить значение атрибутов» внутри действия «Создать запись» со следующими свойствами:

   • Атрибут: Описание
   • Операция со значениями: заменить

   • Значение: формула

     $$HttpRequest->Description 
     

     Здесь Description — имя атрибута для хранения описания файлов, настроенного на вкладке «Атрибуты сообщений» пути передачи данных.

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

   • Переменная: File

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

     $$HttpRequest—>FileObject 
     

     Здесь FileObject — имя атрибута для хранения полученных файлов, настроенного на вкладке «Атрибуты сообщений» пути передачи данных.

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

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

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

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

       # Импортируем функции для работы 
       # с данными текущего сеанса и переменными 
       @prefix document: <http://comindware.com/ontology/document#>. 
       @prefix variable: <http://comindware.com/ontology/session/variable#>. 
       @prefix operator: <http://comindware.com/ontology/session/operator#>. 
       @prefix session: <http://comindware.com/ontology/session#>. 
       { 
           # Находим переменную File из предыдущего действия сценария 
           # и помещаем её в локальную переменную ?File 
           session:context variable:File ?File. 
           # Из ?File достаём содержимое файла 
           # и помещаем его в переменную ?FileContent 
           ?File variable:content ?FileContent. 
           # Из ?File достаём имя файла 
           # и помещаем его в переменную ?Filename 
           ?File variable:name ?Filename. 
           # Помещаем имя и содержимое файла в переменную ?DocumentObject 
           (?FileContent ?Filename) document:attach ?DocumentObject. 
           # Создаём в сценарии переменную ?Document  
           # и помещаем в неё ?DocumentObject 
           variable:Document operator:replace ?DocumentObject. 
           # Возвращаем значение true 
           true -> ?value. 
       } 
       

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

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

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

   • Атрибут: Файлы
   • Операция со значениями: добавить

   • Значение: формула

     $$Document 
     

     Здесь Document — имя переменной, в которую мы помещаем объект с файлом с помощью действия «Проверить результат выражения».

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

1. С внешнего сервера отправьте в Comindware Platform HTTP-запрос с несколькими файлами, например:

   curl -X POST \  
       -u username:password \ 
       -H "Content-Type: multipart/form-data" \ 
       -F "description=Фото и документ" \ 
       -F "files=@image.jpg" \ 
       -F "files=@document.docx" \ 
       https://<hostname>/api/public/adapter/httpListener/uploadFiles \ 
       -v 
   

   Здесь:

   • -X POST — метод запроса (необязательный ключ);
   • -u username:password — базовая аутентификация c учётными данными аккаунта с разрешением на вызовы API Comindware Platform;
   • -H "Content-Type: multipart/form-data" — передача данных в формате составного содержимого;
   • -F "description=Фото и документ" — описание файлов;
   • -F "files=@image.jpg" -F "files=@document.docx" — массив из двух файлов;
   • https://<hostname>/api/public/adapter/httpListener/uploadFiles — базовый путь получения HTTP-запросов и путь URI, настроенные в пути передачи данных;
   • -v — вывод отладочных данных (необязательный ключ).

2. Через некоторое время после отправки HTTP-запроса в шаблоне «Картотека» должна появиться новая запись.

3. Откройте эту запись.
4. В поле «Файлы» должны отображаться файлы, полученные с внешнего сервера, и должно быть заполнено Описание.