Recherche dynamique
La recherche dynamique charge les choix depuis une API distante en temps réel au fil de la saisie de l’enquêteur, permettant des jeux de données volumineux ou fréquemment mis à jour.
La Recherche dynamique (également appelée Search API) permet à un champ select_one, select_multiple ou text de charger ses choix depuis un service web distant au moment de l’exécution, au fil de la saisie de l’enquêteur. C’est la bonne approche lorsque votre liste de choix est trop grande pour être incluse dans un fichier CSV, est mise à jour fréquemment, ou provient d’une base de données en direct.
Apparence search-api()
La recherche dynamique est configurée via la colonne appearance en utilisant la fonction search-api() :
search-api(method, url, post_body, value_column, display, data_path, save_path)
Paramètres
| Paramètre | Description |
|---|---|
method | Utilisez toujours 'POST' |
url | Le point de terminaison API à interroger |
post_body | Corps JSON envoyé à l’API. Utilisez %__input__% comme espace réservé pour le texte de recherche actuel de l’enquêteur |
value_column | La clé dans l’objet de réponse à utiliser comme valeur stockée |
display | La clé (ou modèle) à utiliser comme étiquette affichée dans la liste déroulante. Prend en charge les espaces réservés ##key## et les expressions @{func} |
data_path | JSONPath vers le tableau d’objets de résultat dans la réponse (ex. : $.data, $.hits.hits.*._source) |
save_path | Un nom sous lequel la réponse brute est sauvegardée pour utilisation par d’autres champs |
Exemple de base
Recherche d’établissement de santé où l’enquêteur saisit une partie du nom de l’établissement :
| type | name | label | appearance |
|---|---|---|---|
| select_one | facility | Sélectionner l’établissement de santé | search-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data') |
L’API reçoit {"query": "nair"} lorsque l’enquêteur saisit “nair” et retourne :
{
"results": [
{"id": "HF001", "name": "Nairobi Central Clinic"},
{"id": "HF002", "name": "Nairobi West Hospital"}
]
}
La liste déroulante affiche Nairobi Central Clinic et Nairobi West Hospital ; la valeur stockée est HF001 ou HF002.
Formatage d’affichage avancé
Utiliser des modèles ##key##
Afficher plusieurs champs dans l’étiquette :
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')
Affiché comme : Nairobi Central Clinic (Nairobi).
Utiliser des expressions @{func}
Appliquer une logique conditionnelle dans l’étiquette d’affichage :
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
'@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
'$.data', 'res')
Les résultats actifs affichent ✓ Clinic Name ; les inactifs affichent ✗ Clinic Name.
Définir une valeur par défaut : search-default-api()
Utilisez search-default-api() après search-api() pour pré-remplir le champ avec un choix par défaut chargé depuis un appel API séparé (ex. : lors de la modification d’un enregistrement existant) :
appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')
Séparateur personnalisé pour select_multiple : search-default-separator()
Pour les champs select_multiple, spécifiez comment plusieurs valeurs sélectionnées sont jointes dans la chaîne stockée :
appearance: search-api(...) search-default-separator(' || ')
Le séparateur par défaut est un espace.
Types de questions pris en charge
| Type de question | Cas d’utilisation |
|---|---|
select_one | Sélection unique parmi les résultats de recherche |
select_multiple | Sélections multiples parmi les résultats de recherche |
text | Autocomplétion — l’enquêteur saisit librement mais peut sélectionner une suggestion |
Utiliser les données de réponse sauvegardées
Le save_path stocke l’objet de réponse API complet sous le nom donné. D’autres champs peuvent le référencer avec pulldata() :
| type | name | label | calculation |
|---|---|---|---|
| select_one | facility | Sélectionner l’établissement | search-api(..., 'facility_data') |
| calculate | facility_district | pulldata('facility_data', 'district') | |
| calculate | facility_type | pulldata('facility_data', 'type') |
Bonnes pratiques
- Assurez-vous que votre point de terminaison API répond en 1-2 secondes — les API lentes rendent la recherche peu réactive.
- Utilisez
%__input__%dans lepost_bodypour que l’API ne retourne que les résultats correspondants, pas l’ensemble du jeu de données. - Indexez le champ de recherche côté serveur (ex. : Elasticsearch, index de texte intégral de base de données) pour des réponses rapides.
- Limitez les résultats à 20-50 éléments par requête — retourner des milliers de résultats annule l’intérêt de la recherche.
- Incluez une exigence de longueur minimale de saisie dans l’API pour éviter de déclencher des requêtes larges sur des saisies d’un seul caractère.
Limitations
- La recherche dynamique nécessite une connectivité réseau — elle ne fonctionne pas hors ligne.
- L’espace réservé
%__input__%est injecté tel quel ; assainissez les saisies côté serveur pour prévenir les injections. - Les expressions d’affichage
@{func}complexes peuvent avoir un support limité selon les versions du client rtSurvey.