Вызов API
Call API позволяет опросу получать данные из внешнего веб-сервиса и использовать ответ для заполнения полей или проверки ответов.
Функция Call API позволяет полю опроса выполнять HTTP-запрос к внешнему сервису и использовать ответ для заполнения вычисленного значения или проверки пользовательского ввода. Это обеспечивает поиск в реальном времени, проверку идентификаторов, поиск штрихкодов и любые другие серверные проверки во время сбора данных.
Имеются две функции:
callapi()— получает значение из API и сохраняет его в полеcalculateилиtextcallapi-verify()— вызывает API и блокирует продолжение, если ответ не соответствует ожидаемому значению (используется вconstraint)
callapi() — Получение и сохранение ответа API
Синтаксис
Поместите callapi() в столбец calculation поля calculate или text:
callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)
Параметры
| # | Параметр | Описание |
|---|---|---|
| 1 | method | HTTP-метод: 'GET' или 'POST' |
| 2 | url | URL конечной точки API |
| 3 | allowed_auto | 1 для автоматического вызова при достижении поля; 0 для ручного триггера |
| 4 | max_retry | Максимальное количество повторных попыток при сбое |
| 5 | no_overwrite | 1 для сохранения существующего значения; 0 для всегда перезаписи |
| 6 | extract_expr | JSONPath для извлечения нужного значения из ответа (например, $.data.name) |
| 7 | timeout | Тайм-аут запроса в миллисекундах |
| 8 | lifetime | Время (мс) актуальности кэшированного ответа до повторного получения |
| 9 | response_q | Имя поля для хранения исходного HTTP-кода ответа (например, ${response_status}) |
| 10 | call_type | (Необязательно) Специальный режим вызова: 'lazy-upload' или 'lazy-upload-multiple' |
| 11 | post_body | (Необязательно) Строка тела POST. Ссылайтесь на поля формы через ##fieldname## |
Пример: GET-запрос для поиска домохозяйства по ID
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| text | household_id | ID домохозяйства | ||
| calculate | hh_name | callapi | callapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '') | |
| note | hh_display | Домохозяйство: ${hh_name} |
Пример: POST-запрос с телом JSON
callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')
В post_body используйте ##fieldname## для подстановки текущего значения любого поля формы.
Внешний вид: callapi
Добавьте callapi в столбец appearance поля для включения интеграции с API:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | api_result | callapi | callapi('GET', ...) |
При allowed_auto = 0 rtSurvey показывает кнопку «Получить», которую перечислитель нажимает вручную.
callapi-verify() — Проверка значения через API
callapi-verify() блокирует отправку поля до подтверждения API корректности введённого значения. Используйте в столбце constraint.
Синтаксис
callapi-verify(method, url, extract_expr, match_expr, timeout, constraint_mode, post_body, message)
Параметры
| # | Параметр | Описание |
|---|---|---|
| 1 | method | HTTP-метод: 'GET' или 'POST' |
| 2 | url | Конечная точка API проверки |
| 3 | extract_expr | JSONPath для извлечения ожидаемого значения из ответа |
| 4 | match_expr | Выражение, сравнивающее извлечённое значение со значением поля |
| 5 | timeout | Тайм-аут запроса в миллисекундах |
| 6 | constraint_mode | 'soft' только для предупреждения; 'hard' для блокировки продолжения |
| 7 | post_body | (Необязательно) Тело POST с подстановками ##fieldname## |
| 8 | message | (Необязательно) Сообщение об ошибке. Поддерживает мультиязычность: <en>Invalid!</en><vi>Không hợp lệ!</vi> |
Пример: Проверка штрихкода в реестре активов
| type | name | label | appearance | constraint | constraint_message |
|---|---|---|---|---|---|
| barcode | asset_code | Отсканируйте штрихкод актива | callapi-verify | callapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}') | Актив не найден в реестре |
Использование данных App API совместно с callapi
Объедините callapi() с pulldata('app-api', 'user.token') для внедрения токена аутентифицированного пользователя в запрос API:
callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))
Лучшие практики
- Всегда устанавливайте разумный
timeout(5000–15000 мс) — не используйте 0 или очень высокие значения. - Устанавливайте
allowed_auto=0для проверок, которые перечислитель должен запускать осознанно (например, проверка ID). - Устанавливайте
no_overwrite=1, когда поле может быть отредактировано позже и вы не хотите перезаписи при повторном получении. - Используйте
extract_exprс конкретным JSONPath, а не полагайтесь на необработанный текст ответа. - Тестируйте вызовы API в офлайн-режиме — callapi завершится с ошибкой, но форма должна оставаться завершаемой для некритических полей.
Ограничения
- Требует сетевого соединения в момент вызова — вызовы завершатся неудачей, когда устройство офлайн.
- Ответы API должны быть в формате JSON — XML или текстовые ответы требуют дополнительного разбора.
- Высокая частота вызовов (например, один API-вызов на каждый экземпляр повторения) может замедлять навигацию по форме.