Ricerca dinamica
La ricerca dinamica carica le scelte da un’API remota in tempo reale mentre l’intervistatore digita, consentendo dataset di grandi dimensioni o frequentemente aggiornati.
La Ricerca dinamica (nota anche come Search API) consente a un campo select_one, select_multiple o text di caricare le sue scelte da un servizio web remoto in fase di esecuzione mentre l’intervistatore digita. Questo è l’approccio giusto quando il tuo elenco di scelte è troppo grande per essere incluso in un file CSV, viene aggiornato frequentemente o proviene da un database live.
Appearance search-api()
La ricerca dinamica è configurata attraverso la colonna appearance usando la funzione search-api():
search-api(method, url, post_body, value_column, display, data_path, save_path)
Parametri
| Parametro | Descrizione |
|---|---|
method | Usa sempre 'POST' |
url | L’endpoint API da interrogare |
post_body | Corpo JSON inviato all’API. Usa %__input__% come segnaposto per il testo di ricerca corrente dell’intervistatore |
value_column | La chiave nell’oggetto risposta da usare come valore memorizzato |
display | La chiave (o template) da usare come etichetta mostrata nel dropdown. Supporta segnaposti ##key## ed espressioni @{func} |
data_path | JSONPath all’array di oggetti risultato nella risposta (es. $.data, $.hits.hits.*._source) |
save_path | Un nome con cui salvare la risposta grezza per uso da parte di altri campi |
Esempio di base
Una ricerca di struttura sanitaria dove l’intervistatore digita parte del nome della struttura:
| type | name | label | appearance |
|---|---|---|---|
| select_one | facility | Seleziona struttura sanitaria | search-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data') |
L’API riceve {"query": "nair"} quando l’intervistatore digita “nair” e restituisce:
{
"results": [
{"id": "HF001", "name": "Nairobi Central Clinic"},
{"id": "HF002", "name": "Nairobi West Hospital"}
]
}
Il dropdown mostra Nairobi Central Clinic e Nairobi West Hospital; il valore memorizzato è HF001 o HF002.
Formattazione avanzata della visualizzazione
Usare template ##key##
Mostra più campi nell’etichetta:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')
Visualizzato come: Nairobi Central Clinic (Nairobi).
Usare espressioni @{func}
Applica logica condizionale nell’etichetta di visualizzazione:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
'@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
'$.data', 'res')
I risultati attivi mostrano ✓ Nome clinica; quelli inattivi mostrano ✗ Nome clinica.
Impostare un valore predefinito: search-default-api()
Usa search-default-api() dopo search-api() per pre-popolare il campo con una scelta predefinita caricata da una chiamata API separata (es. quando si modifica un record esistente):
appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')
Separatore personalizzato per select_multiple: search-default-separator()
Per i campi select_multiple, specifica come vengono uniti più valori selezionati nella stringa memorizzata:
appearance: search-api(...) search-default-separator(' || ')
Il separatore predefinito è uno spazio.
Tipi di domanda supportati
| Tipo di domanda | Caso d’uso |
|---|---|
select_one | Selezione singola dai risultati di ricerca |
select_multiple | Selezioni multiple dai risultati di ricerca |
text | Completamento automatico — l’intervistatore digita liberamente ma può selezionare un suggerimento |
Utilizzo dei dati di risposta salvati
Il save_path memorizza l’oggetto di risposta API completo con il nome fornito. Altri campi possono farvi riferimento con pulldata():
| type | name | label | calculation |
|---|---|---|---|
| select_one | facility | Seleziona struttura | search-api(..., 'facility_data') |
| calculate | facility_district | pulldata('facility_data', 'district') | |
| calculate | facility_type | pulldata('facility_data', 'type') |
Best practice
- Assicurati che il tuo endpoint API risponda entro 1–2 secondi — le API lente fanno sembrare la ricerca non reattiva.
- Usa
%__input__%nelpost_bodyin modo che l’API restituisca solo i risultati corrispondenti, non l’intero dataset. - Indicizza il campo di ricerca lato server (es. Elasticsearch, indice full-text del database) per risposte veloci.
- Limita i risultati a 20–50 elementi per query — restituire migliaia di risultati vanifica lo scopo della ricerca.
- Includi un requisito di lunghezza minima dell’input nell’API per evitare di attivare query ampie su input di un singolo carattere.
Limitazioni
- La ricerca dinamica richiede connettività di rete — non funziona offline.
- Il segnaposto
%__input__%viene iniettato così com’è; sanifica gli input lato server per prevenire attacchi di iniezione. - Le espressioni di visualizzazione
@{func}complesse potrebbero avere supporto limitato tra tutte le versioni del client rtSurvey.