HTTP-запросы. Получение и обработка данных с помощью JSONPath

Введение

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

JSONPath — язык запросов к базам данных и информационно-поисковым системам для работы с данными в формате JSON. Аналогичен XPath для работы с данными в формате XML.

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

Настройка с использованием XPath будет аналогичной.

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

Имеется шаблон записи «Картотека», в котором хранятся данные о книгах.

Имеется внешний сервер, выдающий в ответ на HTTP-запрос данные о книгах в формате JSON, например:

{ 
    "Date": "17.10.2024", 
    "Books": [ 
        { 
            "Author": "Толстой Л. Н.", 
            "Title": "Война и мир", 
            "Price": 895 
        }, 
        { 
            "Author": "Пушкин А. С.", 
            "Title": "Капитанская дочка", 
            "Price": 499 
        }, 
        { 
            "Author": "Лермонтов М. Ю.", 
            "Title": "Мцыри", 
            "Price": 372 
        } 
    ] 
} 

Требуется настроить кнопку, загружающую данные о книгах с внешнего сервера посредством HTTP-запроса.
При получении ответа на HTTP-запрос требуется создать записи с данными книг в Картотеке.

Порядок настройки отправки и обработки HTTP-запросов с помощью сценария

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

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

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

Название Тип данных

Автор Текст

Название Текст

Цена Число
Создайте кнопку «Получить данные о книгах» со следующими свойствами:
- Контекст операции: запись
- Операция: вызвать событие «Нажата кнопка»
- Результат выполнения: обновить данные
Поместите созданные атрибуты и кнопку на форму.

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

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

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

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

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

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

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

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

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

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

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

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

Укажите тип сообщения «Отправка HTTP-запросов».
В таблице «Ответ» добавьте атрибут
- Системное имя: Books — должно совпадать с именем соответствующего поля HTTP-запроса.
- Тип: объект
- Массив: флажок установлен
К атрибуту Books добавьте следующие дочерние атрибуты:
- Author типа строка;
- Title типа строка;
- Price типа число.
Системные имена атрибутов должны совпадать с именами соответствующих полей HTTP-запроса.

Интеграция

На вкладке «Интеграция» укажите атрибут для десериализации ответа без ошибки:

Путь к атрибуту: Books — системное имя атрибута с вкладки «Атрибуты сообщения».
Выражение на языке запросов:
$.Books[*]

Обращение к данным с помощью JSONPath

Чтобы обратиться к определённым сегментам данных, полученных из JSON, требуется составить соответствующий запрос на языке JSONPath:

$ — обращение ко всему JSON.
$.object — обращение к объекту object.
$.array[X, Y] — обращение к элементам массива array под номерами X и Y (отсчёт начинается с 0).
$.array[X:Y] — обращение к элементам массива array под номерами от X до Y-1.
$.array[*] — обращение ко всем элементам массива array.

Примеры запросов на JSONPath и возвращаемых значений:

Запрос	Возвращаемое значение
`$`	`{ "Date": "17.10.2024", "Books": [ { "Author": "Толстой Л. Н.", "Title": "Война и мир", "Price": 895 }, { "Author": "Пушкин А. С.", "Title": "Капитанская дочка", "Price": 499 }, { "Author": "Лермонтов М. Ю.", "Title": "Мцыри", "Price": 372 } ] }`
`$.Date`	`"17.10.2024"`
`$.Books[0,2]`	`{ "Author": "Толстой Л. Н.", "Title": "Война и мир", "Price": 895 }, { "Author": "Лермонтов М. Ю.", "Title": "Мцыри", "Price": 372 }`
`$.Books[1].Title`	`"Капитанская дочка"`

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

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

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

Атрибут	Операция со значениями	Значение
Автор	Заменить	Формула: `$$Book->Author`
Название	Заменить	Формула: `$$Book->Title`
Цена	Заменить	Формула: `$$Book->Price`

Сценарий обработки данных из запроса с помощью JSONPath

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

Настройте внешний сервер на отправку ответа на HTTP-запросы с данными в формате JSON, соответствующем прикладной задаче.
В Comindware Platform нажмите кнопку «Получить данные о книгах».
Через некоторое время в шаблоне «Картотека» должны появиться новые записи с данными, полученными с сервера.
Просмотрите новые записи.

Название	Тип данных
Автор	Текст
Название	Текст
Цена	Число