Функція Call API дозволяє полю опитування здійснювати HTTP-запит до зовнішнього сервісу та використовувати відповідь для заповнення обчисленого значення або перевірки введення користувача. Це забезпечує пошук у реальному часі, верифікацію ID, пошук штрих-кодів та будь-яку іншу серверну перевірку під час збору даних.

Є дві функції:

  • callapi() — отримує значення з API та зберігає його в полі calculate або text
  • callapi-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)

Параметри

#ПараметрОпис
1methodHTTP-метод: 'GET' або 'POST'
2urlURL кінцевої точки API
3allowed_auto1 для автоматичного виклику при досягненні поля; 0 для ручного запуску
4max_retryМаксимальна кількість спроб при збої
5no_overwrite1 для збереження існуючого значення якщо поле вже має значення; 0 для завжди перезаписування
6extract_exprJSONPath-вираз для витягування потрібного значення з відповіді (наприклад, $.data.name)
7timeoutТайм-аут запиту в мілісекундах
8lifetimeЧас (мс) дійсності кешованої відповіді перед повторним отриманням
9response_qНазва поля для зберігання необробленого HTTP-коду відповіді (наприклад, ${response_status})
10call_type(Необов’язково) Спеціальний режим виклику: 'lazy-upload' або 'lazy-upload-multiple'
11post_body(Необов’язково) Рядок тіла POST. Посилайтесь на поля форми через ##fieldname##

Приклад: GET-запит для пошуку домогосподарства за ID

typenamelabelappearancecalculation
texthousehold_idHousehold ID
calculatehh_namecallapicallapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '')
notehh_displayHousehold: ${hh_name}

Приклад: POST-запит з тілом JSON 

  callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')

У post_body використовуйте ##fieldname## для підстановки поточного значення будь-якого поля форми.

Appearance: callapi

Додайте callapi до стовпця appearance поля для увімкнення інтеграції API-виклику:

typenamelabelappearancecalculation
calculateapi_resultcallapicallapi('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)

Параметри

#ПараметрОпис
1methodHTTP-метод: 'GET' або 'POST'
2urlКінцева точка API верифікації
3extract_exprJSONPath для витягування очікуваного значення з відповіді
4match_exprВираз, що порівнює витягнуте значення зі значенням поля
5timeoutТайм-аут запиту в мілісекундах
6constraint_mode'soft' лише для попередження; 'hard' для блокування прогресу
7post_body(Необов’язково) Тіло POST із замінами ##fieldname##
8message(Необов’язково) Повідомлення про помилку. Підтримує кілька мов: <en>Invalid!</en><vi>Không hợp lệ!</vi>

Приклад: Верифікація штрих-коду через реєстр активів

typenamelabelappearanceconstraintconstraint_message
barcodeasset_codeScan the asset barcodecallapi-verifycallapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}')Asset not found in registry

Використання даних 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##"}'))

Найкращі практики

  1. Завжди встановлюйте розумний timeout (5000–15000 мс) — не використовуйте 0 або дуже великі значення.
  2. Встановіть allowed_auto=0 для верифікацій, які анкетер повинен запускати свідомо.
  3. Встановіть no_overwrite=1, коли поле може бути відредаговано пізніше.
  4. Використовуйте extract_expr з конкретним JSONPath.
  5. Тестуйте API-виклики в офлайн-режимі.

Обмеження

  • Потребує підключення до мережі — виклики не вдаться, коли пристрій офлайн.
  • Відповіді API повинні бути JSON — XML або відповіді у вигляді звичайного тексту потребують додаткового аналізу.
  • Висока частота викликів може уповільнити навігацію формою.
Чи була ця сторінка корисною?