API aanroepen
Met API aanroepen kan uw enquête gegevens ophalen uit een externe webservice en de respons gebruiken om velden te vullen of antwoorden te valideren.
De functie API aanroepen stelt een enquêteveld in staat een HTTP-verzoek te doen aan een externe service en de respons te gebruiken om een berekende waarde in te vullen of gebruikersinvoer te valideren. Dit maakt realtime opzoekacties, ID-verificatie, barcode-opzoekacties en elke andere servercontrole tijdens de gegevensverzameling mogelijk.
Er zijn twee functies:
callapi()— haalt een waarde op uit een API en slaat deze op in eencalculate- oftext-veldcallapi-verify()— roept een API aan en blokkeert voortgang als de respons niet overeenkomt met de verwachte waarde (gebruikt inconstraint)
callapi() — Een API-respons ophalen en opslaan
Syntaxis
Plaats callapi() in de kolom calculation van een calculate- of text-veld:
callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)
Parameters
| # | Parameter | Beschrijving |
|---|---|---|
| 1 | method | HTTP-methode: 'GET' of 'POST' |
| 2 | url | API-endpoint URL |
| 3 | allowed_auto | 1 om automatisch aan te roepen wanneer het veld wordt bereikt; 0 om een handmatige triggerknop te vereisen |
| 4 | max_retry | Maximum aantal nieuwe pogingen bij mislukking |
| 5 | no_overwrite | 1 om de bestaande waarde te behouden als het veld al een waarde heeft; 0 om altijd te overschrijven |
| 6 | extract_expr | JSONPath-expressie om de gewenste waarde uit de respons te extraheren (bijv. $.data.name) |
| 7 | timeout | Time-out voor verzoek in milliseconden |
| 8 | lifetime | Hoe lang (ms) de gecachede respons geldig blijft voor opnieuw ophalen |
| 9 | response_q | Naam van een veld om de ruwe HTTP-responscode op te slaan (bijv. ${response_status}) |
| 10 | call_type | (Optioneel) Speciale aanroepmodus: 'lazy-upload' of 'lazy-upload-multiple' |
| 11 | post_body | (Optioneel) POST-body tekenreeks. Verwijs naar formuliervelden met ##veldnaam## |
Voorbeeld: GET-verzoek om een huishouden op te zoeken via ID
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| text | household_id | Huishoud-ID | ||
| calculate | hh_name | callapi | callapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '') | |
| note | hh_display | Huishouden: ${hh_name} |
Voorbeeld: POST-verzoek met een JSON-body
callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')
Gebruik in de post_body ##veldnaam## om de huidige waarde van een formulierveld in te voegen.
Weergave: callapi
Voeg callapi toe aan de kolom appearance van het veld om de API-aanroepintegratie in te schakelen:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | api_result | callapi | callapi('GET', ...) |
Wanneer allowed_auto 0 is, toont rtSurvey een “Ophalen”-knop die de enumerator handmatig indrukt.
callapi-verify() — Een waarde valideren tegen een API
callapi-verify() blokkeert de indiening van een veld totdat een API bevestigt dat de ingevoerde waarde geldig is. Gebruik het in de kolom constraint.
Syntaxis
callapi-verify(method, url, extract_expr, match_expr, timeout, constraint_mode, post_body, message)
Parameters
| # | Parameter | Beschrijving |
|---|---|---|
| 1 | method | HTTP-methode: 'GET' of 'POST' |
| 2 | url | Verificatie API-endpoint |
| 3 | extract_expr | JSONPath om de verwachte waarde uit de respons te extraheren |
| 4 | match_expr | Expressie die de geëxtraheerde waarde vergelijkt met de veldwaarde (bijv. $.status = 'valid') |
| 5 | timeout | Time-out voor verzoek in milliseconden |
| 6 | constraint_mode | 'soft' voor alleen een waarschuwing; 'hard' om voortgang te blokkeren |
| 7 | post_body | (Optioneel) POST-body met ##veldnaam##-vervangingen |
| 8 | message | (Optioneel) Foutmelding. Ondersteunt meerdere talen: <en>Invalid!</en><vi>Không hợp lệ!</vi> |
Voorbeeld: Een barcode verifiëren tegen een activaregister
| type | name | label | appearance | constraint | constraint_message |
|---|---|---|---|---|---|
| barcode | asset_code | Scan de activabarcode | callapi-verify | callapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}') | Activa niet gevonden in register |
Weergave: callapi-verify(...)
De kolom appearance op een veld met callapi-verify() in constraint moet callapi-verify(params) of callapi-verify(dynamicParams) bevatten om aan rtSurvey aan te geven dat dit veld API-verificatie gebruikt.
App API-gegevens gebruiken naast callapi
Combineer callapi() met pulldata('app-api', 'user.token') om de token van de geauthenticeerde gebruiker in uw API-verzoek te injecteren:
callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))
Aanbevolen werkwijzen
- Stel altijd een redelijke
timeoutin (5000–15000 ms) — gebruik geen 0 of zeer hoge waarden. - Stel
allowed_auto=0in voor verificaties die de enumerator bewust moet activeren (bijv. ID-controles). - Stel
no_overwrite=1in wanneer het veld later kan worden bewerkt en u niet wilt dat opnieuw ophalen handmatige correcties overschrijft. - Gebruik
extract_exprmet een specifiek JSONPath in plaats van te vertrouwen op ruwe responstekst. - Test API-aanroepen in de offlinemodus — callapi mislukt op een nette manier en toont een fout, maar het formulier moet nog steeds te voltooien zijn voor niet-kritieke velden.
Beperkingen
- Vereist netwerkconnectiviteit op het moment van de aanroep — aanroepen mislukken wanneer het apparaat offline is.
- API-responsen moeten JSON zijn — XML- of platte-tekstreponsen vereisen aanvullende verwerking.
- Hoge aanroepfrequentie (bijv. één API-aanroep per herhalingsinstantie) kan formuliernavigatie vertragen.