Call API
Call API consente al tuo sondaggio di recuperare dati da un servizio web esterno e usare la risposta per popolare campi o validare risposte.
La funzionalità Call API consente a un campo del sondaggio di effettuare una richiesta HTTP a un servizio esterno e usare la risposta per popolare un valore calcolato o validare l’input dell’utente. Questo abilita ricerche in tempo reale, verifica ID, ricerche barcode e qualsiasi altro controllo lato server durante la raccolta dati.
Esistono due funzioni:
callapi()— recupera un valore da un’API e lo memorizza in un campocalculateotextcallapi-verify()— chiama un’API e blocca l’avanzamento se la risposta non corrisponde al valore atteso (usata inconstraint)
callapi() — Recupera e memorizza una risposta API
Sintassi
Inserisci callapi() nella colonna calculation di un campo calculate o text:
callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)
Parametri
| # | Parametro | Descrizione |
|---|---|---|
| 1 | method | Metodo HTTP: 'GET' o 'POST' |
| 2 | url | URL dell’endpoint API |
| 3 | allowed_auto | 1 per chiamare automaticamente quando si raggiunge il campo; 0 per richiedere un pulsante di attivazione manuale |
| 4 | max_retry | Numero massimo di tentativi in caso di errore |
| 5 | no_overwrite | 1 per mantenere il valore esistente se il campo ne ha già uno; 0 per sovrascrivere sempre |
| 6 | extract_expr | Espressione JSONPath per estrarre il valore desiderato dalla risposta (es. $.data.name) |
| 7 | timeout | Timeout della richiesta in millisecondi |
| 8 | lifetime | Per quanto tempo (ms) la risposta memorizzata nella cache rimane valida prima di recuperarla nuovamente |
| 9 | response_q | Nome di un campo per memorizzare il codice di risposta HTTP grezzo (es. ${response_status}) |
| 10 | call_type | (Opzionale) Modalità di chiamata speciale: 'lazy-upload' o 'lazy-upload-multiple' |
| 11 | post_body | (Opzionale) Stringa del corpo POST. Fai riferimento ai campi del modulo con ##fieldname## |
Esempio: Richiesta GET per cercare un nucleo familiare per ID
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| text | household_id | ID nucleo familiare | ||
| calculate | hh_name | callapi | callapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '') | |
| note | hh_display | Nucleo familiare: ${hh_name} |
Esempio: Richiesta POST con corpo JSON
callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')
Nel post_body, usa ##fieldname## per iniettare il valore corrente di qualsiasi campo del modulo.
Appearance: callapi
Aggiungi callapi alla colonna appearance del campo per abilitare l’integrazione della chiamata API:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | api_result | callapi | callapi('GET', ...) |
Quando allowed_auto è 0, rtSurvey mostra un pulsante “Recupera” che l’intervistatore tocca manualmente.
callapi-verify() — Valida un valore con un’API
callapi-verify() blocca l’invio di un campo finché un’API non conferma che il valore inserito è valido. Usalo nella colonna constraint.
Sintassi
callapi-verify(method, url, extract_expr, match_expr, timeout, constraint_mode, post_body, message)
Parametri
| # | Parametro | Descrizione |
|---|---|---|
| 1 | method | Metodo HTTP: 'GET' o 'POST' |
| 2 | url | Endpoint API di verifica |
| 3 | extract_expr | JSONPath per estrarre il valore atteso dalla risposta |
| 4 | match_expr | Espressione che confronta il valore estratto con il valore del campo (es. $.status = 'valid') |
| 5 | timeout | Timeout della richiesta in millisecondi |
| 6 | constraint_mode | 'soft' solo per un avviso; 'hard' per bloccare l’avanzamento |
| 7 | post_body | (Opzionale) Corpo POST con sostituzioni ##fieldname## |
| 8 | message | (Opzionale) Messaggio di errore. Supporta multilingua: <en>Invalid!</en><vi>Không hợp lệ!</vi> |
Esempio: Verifica un barcode contro un registro asset
| type | name | label | appearance | constraint | constraint_message |
|---|---|---|---|---|---|
| barcode | asset_code | Scansiona il barcode dell’asset | callapi-verify | callapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}') | Asset non trovato nel registro |
Appearance: callapi-verify(...)
La colonna appearance su un campo con callapi-verify() nel constraint dovrebbe contenere callapi-verify(params) o callapi-verify(dynamicParams) per segnalare a rtSurvey che questo campo usa la verifica API.
Usare i dati App API insieme a callapi
Combina callapi() con pulldata('app-api', 'user.token') per iniettare il token dell’utente autenticato nella tua richiesta API:
callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))
Best practice
- Imposta sempre un
timeoutragionevole (5000–15000 ms) — non usare 0 o valori molto alti. - Imposta
allowed_auto=0per le verifiche che l’intervistatore dovrebbe attivare consapevolmente (es. controlli ID). - Imposta
no_overwrite=1quando il campo potrebbe essere modificato in seguito e non vuoi che il recupero sovrascriva le correzioni manuali. - Usa
extract_exprcon un JSONPath specifico piuttosto che fare affidamento sul testo grezzo della risposta. - Testa le chiamate API in modalità offline — callapi fallirà normalmente e mostrerà un errore, ma il modulo dovrebbe comunque essere completabile per i campi non critici.
Limitazioni
- Richiede connettività di rete al momento della chiamata — le chiamate falliranno quando il dispositivo è offline.
- Le risposte API devono essere JSON — le risposte XML o in testo normale richiedono elaborazione aggiuntiva.
- Un’alta frequenza di chiamate (es. una chiamata API per istanza di ripetizione) può rallentare la navigazione nel modulo.