Funkcia Volanie API umožňuje poľu prieskumu vykonať HTTP požiadavku na externú službu a použiť odpoveď na vyplnenie vypočítanej hodnoty alebo overenie vstupu používateľa. To umožňuje vyhľadávania v reálnom čase, overovanie ID, vyhľadávania čiarových kódov a akékoľvek iné serverové kontroly počas zberu dát.

Existujú dve funkcie:

  • callapi() — načíta hodnotu z API a uloží ju do poľa calculate alebo text
  • callapi-verify() — zavolá API a zablokuje postup ak odpoveď nezodpovedá očakávanej hodnote (používa sa v constraint)

callapi() — Načítanie a uloženie odpovede API

Syntax

Umiestnite callapi() do stĺpca calculation poľa calculate alebo text:

  callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)

Parametre

#ParameterPopis
1methodHTTP metóda: 'GET' alebo 'POST'
2urlURL koncového bodu API
3allowed_auto1 na automatické volanie keď je pole dosiahnuté; 0 na vyžadovanie manuálneho tlačidla
4max_retryMaximálny počet pokusov pri zlyhaní
5no_overwrite1 na zachovanie existujúcej hodnoty ak pole už má jednu; 0 na vždy prepísanie
6extract_exprVýraz JSONPath na extrahovanie požadovanej hodnoty z odpovede (napr. $.data.name)
7timeoutČasový limit požiadavky v milisekundách
8lifetimeAko dlho (ms) zostáva uložená odpoveď platná pred opätovným načítaním
9response_qNázov poľa na uloženie surového HTTP kódu odpovede (napr. ${response_status})
10call_type(Voliteľné) Špeciálny režim volania: 'lazy-upload' alebo 'lazy-upload-multiple'
11post_body(Voliteľné) Reťazec tela POST. Odkazujte na polia formulára pomocou ##fieldname##

Príklad: GET požiadavka na vyhľadanie domácnosti podľa ID

typenamelabelappearancecalculation
texthousehold_idID domácnosti
calculatehh_namecallapicallapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '')
notehh_displayDomácnosť: ${hh_name}

Príklad: POST požiadavka s JSON telom 

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

V post_body použite ##fieldname## na vloženie aktuálnej hodnoty ľubovoľného poľa formulára.

Vzhľad: callapi

Pridajte callapi do stĺpca appearance poľa na povolenie integrácie volania API:

typenamelabelappearancecalculation
calculateapi_resultcallapicallapi('GET', ...)

Keď je allowed_auto 0, rtSurvey zobrazí tlačidlo „Načítať", ktoré anketár ťuká manuálne.

callapi-verify() — Overenie hodnoty voči API

callapi-verify() blokuje odoslanie poľa, kým API nepotvrdí, že zadaná hodnota je platná. Použite ho v stĺpci constraint.

Syntax 

  callapi-verify(method, url, extract_expr, match_expr, timeout, constraint_mode, post_body, message)

Parametre

#ParameterPopis
1methodHTTP metóda: 'GET' alebo 'POST'
2urlOverovací koncový bod API
3extract_exprJSONPath na extrahovanie očakávanej hodnoty z odpovede
4match_exprVýraz porovnávajúci extrahovanú hodnotu s hodnotou poľa (napr. $.status = 'valid')
5timeoutČasový limit požiadavky v milisekundách
6constraint_mode'soft' iba pre varovanie; 'hard' na blokovanie postupu
7post_body(Voliteľné) Telo POST so substitúciami ##fieldname##
8message(Voliteľné) Chybová správa. Podporuje viacero jazykov: <en>Invalid!</en><sk>Neplatné!</sk>

Príklad: Overenie čiarového kódu voči registru majetku

typenamelabelappearanceconstraintconstraint_message
barcodeasset_codeNaskenujte čiarový kód majetkucallapi-verifycallapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}')Majetok nebol nájdený v registri

Vzhľad: callapi-verify(...)

Stĺpec appearance na poli s callapi-verify() v constraint by mal obsahovať callapi-verify(params) alebo callapi-verify(dynamicParams) na signalizáciu rtSurvey, že toto pole používa overovanie API.

Používanie dát App API spolu s callapi

Kombinujte callapi() s pulldata('app-api', 'user.token') na vloženie tokenu autentifikovaného používateľa do vašej API požiadavky:

  callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
  concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))

Najlepšie postupy

  1. Vždy nastavte rozumný timeout (5000–15000 ms) — nepoužívajte 0 alebo veľmi vysoké hodnoty.
  2. Nastavte allowed_auto=0 pre overenia, ktoré by mal anketár spúšťať vedome (napr. kontroly ID).
  3. Nastavte no_overwrite=1 keď môže byť pole neskôr editované a nechcete, aby opätovné načítanie prepísalo manuálne opravy.
  4. Používajte extract_expr so špecifickým JSONPath namiesto spoliehania sa na surový text odpovede.
  5. Testujte volania API v offline režime — callapi zlyhá elegantne a zobrazí chybu, ale formulár by mal byť stále vyplniteľný pre nekritické polia.

Obmedzenia

  • Vyžaduje sieťové pripojenie v čase volania — volania zlyhajú, keď je zariadenie offline.
  • Odpovede API musia byť JSON — XML alebo odpovede s čistým textom vyžadujú ďalšie parsovanie.
  • Vysoká frekvencia volaní (napr. jedno API volanie na inštanciu opakovania) môže spomaliť navigáciu vo formulári.
Bola táto stránka užitočná?