Call API
Call API antaa kyselykentän tehdä HTTP-pyynnön ulkoiseen palveluun ja käyttää vastausta kenttien täyttämiseen tai vastausten validoimiseen.
Call API -ominaisuus mahdollistaa kyselykentän tekemän HTTP-pyynnön ulkoiseen palveluun ja vastauksen käyttämisen lasketun arvon täyttämiseen tai käyttäjäsyötteen validoimiseen. Tämä mahdollistaa reaaliaikaiset hakutoiminnot, henkilöllisyyden varmennus, viivakoodihaut ja muut palvelinpuolen tarkistukset tiedonkeruun aikana.
Saatavilla on kaksi funktiota:
callapi()— hakee arvon API:sta ja tallentaa sencalculate- taitext-kenttääncallapi-verify()— kutsuu API:a ja estää etenemisen, jos vastaus ei vastaa odotettua arvoa (käytetäänconstraint-kohdassa)
callapi() — Hae ja tallenna API-vastaus
Syntaksi
Sijoita callapi() calculate- tai text-kentän calculation-sarakkeeseen:
callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)
Parametrit
| # | Parametri | Kuvaus |
|---|---|---|
| 1 | method | HTTP-metodi: 'GET' tai 'POST' |
| 2 | url | API-päätepisteen URL |
| 3 | allowed_auto | 1 kutsuaksesi automaattisesti kun kenttä saavutetaan; 0 vaatimaan manuaalinen käynnistinpainike |
| 4 | max_retry | Uudelleenyrityskertojen enimmäismäärä virheen sattuessa |
| 5 | no_overwrite | 1 säilyttääksesi olemassa olevan arvon jos kentällä on jo arvo; 0 ylikirjoittaaksesi aina |
| 6 | extract_expr | JSONPath-lauseke halutun arvon poimimiseen vastauksesta (esim. $.data.name) |
| 7 | timeout | Pyyntöaikakatkaisu millisekunteina |
| 8 | lifetime | Kuinka kauan (ms) välimuistissa oleva vastaus pysyy voimassa ennen uudelleenhakua |
| 9 | response_q | HTTP-vastauksen raakakoodi tallentavan kentän nimi (esim. ${response_status}) |
| 10 | call_type | (Valinnainen) Erityinen kutsutila: 'lazy-upload' tai 'lazy-upload-multiple' |
| 11 | post_body | (Valinnainen) POST-runkomerkkijono. Viittaa lomakekenttiin käyttämällä ##fieldname## |
Esimerkki: GET-pyyntö kotitalouden hakemiseksi tunnuksella
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| text | household_id | Kotitaloustunnus | ||
| calculate | hh_name | callapi | callapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '') | |
| note | hh_display | Kotitalous: ${hh_name} |
Esimerkki: POST-pyyntö JSON-rungolla
callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')
post_body-kohdassa käytä ##fieldname## syöttääksesi minkä tahansa lomakekentän nykyisen arvon.
Ulkoasu: callapi
Lisää callapi kentän appearance-sarakkeeseen mahdollistaaksesi API-kutsuintegraation:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | api_result | callapi | callapi('GET', ...) |
Kun allowed_auto on 0, rtSurvey näyttää “Hae”-painikkeen, jonka luetteloija napauttaa manuaalisesti.
callapi-verify() — Validoi arvo API:ta vasten
callapi-verify() estää kentän lähettämisen, kunnes API vahvistaa syötetyn arvon olevan kelvollinen. Käytä sitä constraint-sarakkeessa.
Syntaksi
callapi-verify(method, url, extract_expr, match_expr, timeout, constraint_mode, post_body, message)
Parametrit
| # | Parametri | Kuvaus |
|---|---|---|
| 1 | method | HTTP-metodi: 'GET' tai 'POST' |
| 2 | url | Varmistus-API-päätepiste |
| 3 | extract_expr | JSONPath vastauksesta odotettavan arvon poimimiseen |
| 4 | match_expr | Lauseke, joka vertaa poimittu arvoa kenttäarvoon (esim. $.status = 'valid') |
| 5 | timeout | Pyyntöaikakatkaisu millisekunteina |
| 6 | constraint_mode | 'soft' vain varoitukselle; 'hard' estämään eteneminen |
| 7 | post_body | (Valinnainen) POST-runko ##fieldname##-korvauksilla |
| 8 | message | (Valinnainen) Virheilmoitus. Tukee monilingvistisyyttä: <en>Invalid!</en><vi>Không hợp lệ!</vi> |
Esimerkki: Viivakoodin varmennus käyttöomaisuusrekisteriä vasten
| type | name | label | appearance | constraint | constraint_message |
|---|---|---|---|---|---|
| barcode | asset_code | Skannaa käyttöomaisuuden viivakoodi | callapi-verify | callapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}') | Käyttöomaisuutta ei löydy rekisteristä |
Ulkoasu: callapi-verify(...)
Kentän appearance-sarakkeen, jossa constraint-kohdassa on callapi-verify(), tulisi sisältää callapi-verify(params) tai callapi-verify(dynamicParams) signaloidakseen rtSurveylle, että tämä kenttä käyttää API-varmennusta.
App API -datan käyttö callapi:n ohella
Yhdistä callapi() ja pulldata('app-api', 'user.token') syöttääksesi todennetun käyttäjän tokenin API-pyyntöön:
callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))
Parhaat käytännöt
- Aseta aina kohtuullinen
timeout(5000–15000 ms) — älä käytä 0:aa tai erittäin suuria arvoja. - Aseta
allowed_auto=0varmenuksille, jotka luetteloijan tulee käynnistää tietoisesti (esim. henkilöllisyystarkistukset). - Aseta
no_overwrite=1, kun kenttää saatetaan muokata myöhemmin eikä halua uudelleenhaun ylikirjoittavan manuaalisia korjauksia. - Käytä
extract_expr-kohdassa tarkka JSONPath-lauseke eikä raaka vastausteksti. - Testaa API-kutsut offline-tilassa — callapi epäonnistuu kauniisti ja näyttää virheen, mutta lomakkeen tulee silti olla täytettävissä ei-kriittisille kentille.
Rajoitukset
- Vaatii verkkoyhteyden kutsun aikaan — kutsut epäonnistuvat, kun laite on offline-tilassa.
- API-vastausten on oltava JSON-muotoisia — XML- tai pelkkätekstivastaukset vaativat lisäparsimista.
- Suuri kutsujen tiheys (esim. yksi API-kutsu per toistotapaus) voi hidastaa lomakenavigoinnin.