Funktionen Kald API lader et undersøgelsesfelt foretage en HTTP-anmodning til en ekstern tjeneste og bruge svaret til at udfylde en beregnet værdi eller validere brugerinput. Dette muliggør realtidsopslag, ID-verifikation, stregkodeopslag og enhver anden serverside-kontrol under dataindsamlingen.

Der er to funktioner:

  • callapi() — henter en værdi fra et API og gemmer den i et calculate- eller text-felt
  • callapi-verify() — kalder et API og blokerer fremgang, hvis svaret ikke matcher den forventede værdi (bruges i constraint)

callapi() — Hent og gem et API-svar

Syntaks

Placer callapi() i kolonnen calculation i et calculate- eller text-felt:

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

Parametre

#ParameterBeskrivelse
1methodHTTP-metode: 'GET' eller 'POST'
2urlAPI-endepunkt-URL
3allowed_auto1 for automatisk at kalde, når feltet nås; 0 for at kræve en manuel udløserknap
4max_retryMaksimalt antal genforsøg ved fejl
5no_overwrite1 for at beholde den eksisterende værdi, hvis feltet allerede har en; 0 for altid at overskrive
6extract_exprJSONPath-udtryk til at udtrække den ønskede værdi fra svaret (f.eks. $.data.name)
7timeoutAnmodningstimeout i millisekunder
8lifetimeHvor længe (ms) det cachelagrede svar forbliver gyldigt inden genindlæsning
9response_qNavn på et felt til lagring af den rå HTTP-svarkode
10call_type(Valgfrit) Speciel kaldtilstand: 'lazy-upload' eller 'lazy-upload-multiple'
11post_body(Valgfrit) POST-tekststreng. Reference til formularfelter med ##fieldname##

Eksempel: GET-anmodning til opslag af en husholdning efter ID

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

Eksempel: POST-anmodning med en JSON-tekst 

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

callapi-verify() — Valider en værdi mod et API

callapi-verify() blokerer indsendelse af et felt, indtil et API bekræfter, at den indtastede værdi er gyldig. Brug det i kolonnen constraint.

Parametre

#ParameterBeskrivelse
1methodHTTP-metode: 'GET' eller 'POST'
2urlVerifikations-API-endepunkt
3extract_exprJSONPath til at udtrække den forventede værdi fra svaret
4match_exprUdtryk der sammenligner den udtrukne værdi med feltets værdi
5timeoutAnmodningstimeout i millisekunder
6constraint_mode'soft' for en advarsel kun; 'hard' for at blokere fremgang
7post_body(Valgfrit) POST-tekst med ##fieldname##-substitutioner
8message(Valgfrit) Fejlmeddelelse med flersproget understøttelse

Bedste praksis

  1. Angiv altid en rimelig timeout (5000–15000 ms).
  2. Sæt allowed_auto=0 til verifikationer, som intervieweren skal udløse bevidst.
  3. Sæt no_overwrite=1, når feltet muligvis redigeres senere.
  4. Brug extract_expr med en specifik JSONPath frem for at stole på rå svartekst.
  5. Test API-kald i offline-tilstand – callapi fejler yndefuldt og viser en fejl, men formularen bør stadig kunne udfyldes for ikke-kritiske felter.

Begrænsninger

  • Kræver netværksforbindelse på tidspunktet for kaldet.
  • API-svar skal være JSON.
  • Høj kaldfrekvens kan sænke formularnavigationen.
Var denne side nyttig?