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

Введение

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

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

Логика обработки входящих 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-запросы. Получение JSON-данных в сценарии»

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

Имеется шаблон записи «Картотека».
К каждой записи в Картотеке можно прикрепить несколько файлов и добавить описание.
Имеется внешний сервер, отправляющий HTTP-запросы в формате multipart/form-data с файлами вида:
{ "description": "STRING", "files":[ { "name": "STRING", "content": "STRING" } ] }
Требуется настроить получение с внешнего сервера HTTP-запросов с файлами.
При получении HTTP-запроса требуется создать запись в Картотеке, прикрепить к ней полученные файлы и заполнить Описание.

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

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

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

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

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

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

Структура атрибута типа «Документ»

Атрибут типа «Документ» хранит одну или несколько ссылок на записи (документы) в системном шаблоне документа, к которым прикрепляются файлы (например, загруженные пользователями).
В шаблоне документа имеется атрибут currentRevision (текущая версия), который хранит ссылку на запись в системном шаблоне версии.
В шаблоне версии имеются атрибуты title (имя) и content (содержимое), которые хранят имя файла и ссылку на файл, физически хранящийся в папке Streams на сервере.

Извлечение файлов из атрибута типа «Документ» с помощью N3

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

получить объект с атрибутом:

("TemplateSystemName" "DocumentAttributeSystemName") object:findProperty ?DocumentAttribute. 

из объекта с атрибутом получить значение атрибута в текущей записи:
?item documentAttribute ?documentAttributeValue.
из значения атрибута получить текущую версию документа:
?documentAttributeValue document:revision ?revision.
из версии получить содержимое файла в формате base64:
?revision document:content ?content.
из версии получить имя файла:
?revision document:title ?title.

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

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

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

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

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

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

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

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

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

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

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

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

Внимание!

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

Интеграция

Укажите дополнительный путь URI, например uploadFiles.
Формирование адреса для входящих HTTP-запросов

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

Укажите результирующий адрес на внешнем сервере в качестве получателя запросов, например:
https://<hostname>/api/public/adapter/httpListener/uploadFiles
В таблицу «Укажите атрибуты для преобразования составного содержимого запроса» сопоставьте атрибуты сообщения (Имя атрибута) с полями HTTP-запросов (Имя части составного содержимого):

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

Description description

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

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

Создайте сценарий «Получение документов через HTTP».
Откройте событие «Нажатие кнопки» и настройте его следующим образом:
- Тип: получение сообщения;
- Контекстный шаблон: Картотека;
- Подключение: подключение для получения документов с помощью HTTP-запросов;
- Путь передачи данных: путь передачи данных для получения документов с помощью HTTP-запросов;
- Имя переменной: HttpRequest — в эту переменную будет сохраняться полученный HTTP-запрос. Имя переменной может быть произвольным.
Добавьте действие «Создать запись» для контекстного шаблона «Картотека».
Добавьте действие «Изменить значение атрибутов» внутри действия «Создать запись» со следующими свойствами:
- Атрибут: Описание
- Операция со значениями: заменить
- Значение: формула
  $$HttpRequest->Description
  Здесь Description — имя атрибута для хранения описания файлов, настроенного на вкладке «Атрибуты сообщений» пути передачи данных.
Добавьте действие «Повторять по количеству объектов» внутри действия «Создать запись» со следующими свойствами:
- Переменная: File
- Атрибут или выражение для поиска объектов: формула
  $$HttpRequest—>FileObject
  Здесь FileObject — имя атрибута для хранения полученных файлов, настроенного на вкладке «Атрибуты сообщений» пути передачи данных.

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

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

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

Выражение: 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. 
} 

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

Добавьте действие «Изменить значение атрибутов» внутри действия «Повторять по количеству объектов» со следующими свойствами:
- Атрибут: Файлы
- Операция со значениями: добавить
- Значение: формула
  $$Document
  Здесь Document — имя переменной, в которую мы помещаем объект с файлом с помощью действия «Проверить результат выражения».

Сценарий получения вложений с помощью HTTP-запросов

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

С внешнего сервера отправьте в 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 — вывод отладочных данных (необязательный ключ).
Через некоторое время после отправки HTTP-запроса в шаблоне «Картотека» должна появиться новая запись.
Откройте эту запись.
В поле «Файлы» должны отображаться файлы, полученные с внешнего сервера, и должно быть заполнено Описание.

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