Dynamische Suche
Die dynamische Suche lädt Auswahlmöglichkeiten in Echtzeit von einer Remote-API, während der Interviewer tippt, und ermöglicht so große oder häufig aktualisierte Datensätze.
Die Dynamische Suche (auch Search API genannt) ermöglicht es einem select_one-, select_multiple- oder text-Feld, seine Auswahlmöglichkeiten zur Laufzeit von einem Remote-Webdienst zu laden, während der Interviewer tippt. Dies ist der richtige Ansatz, wenn Ihre Auswahlliste zu groß ist, um sie in einer CSV-Datei zu bündeln, häufig aktualisiert wird oder aus einer Live-Datenbank stammt.
search-api()-Erscheinungsbild
Die dynamische Suche wird über die Spalte appearance mit der Funktion search-api() konfiguriert:
search-api(method, url, post_body, value_column, display, data_path, save_path)
Parameter
| Parameter | Beschreibung |
|---|---|
method | Immer 'POST' verwenden |
url | Der abzufragende API-Endpunkt |
post_body | JSON-Body, der an die API gesendet wird. Verwenden Sie %__input__% als Platzhalter für den aktuellen Suchtext des Interviewers |
value_column | Der Schlüssel im Antwortobjekt, der als gespeicherter Wert verwendet wird |
display | Der Schlüssel (oder die Vorlage), der als Beschriftung im Dropdown angezeigt wird. Unterstützt ##key##-Platzhalter und @{func}-Ausdrücke |
data_path | JSONPath zum Array der Ergebnisobjekte in der Antwort (z. B. $.data, $.hits.hits.*._source) |
save_path | Ein Name, unter dem die Rohantwort für die Verwendung durch andere Felder gespeichert wird |
Grundlegendes Beispiel
Eine Gesundheitseinrichtungs-Suche, bei der der Interviewer einen Teil des Einrichtungsnamens eingibt:
| type | name | label | appearance |
|---|---|---|---|
| select_one | facility | Gesundheitseinrichtung auswählen | search-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data') |
Die API erhält {"query": "nair"}, wenn der Interviewer “nair” tippt, und gibt zurück:
{
"results": [
{"id": "HF001", "name": "Nairobi Central Clinic"},
{"id": "HF002", "name": "Nairobi West Hospital"}
]
}
Das Dropdown zeigt Nairobi Central Clinic und Nairobi West Hospital an; der gespeicherte Wert ist HF001 oder HF002.
Erweiterte Anzeigeformatierung
Verwendung von ##key##-Vorlagen
Mehrere Felder in der Beschriftung anzeigen:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')
Wird angezeigt als: Nairobi Central Clinic (Nairobi).
Verwendung von @{func}-Ausdrücken
Bedingte Logik in der Anzeigebeschriftung anwenden:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
'@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
'$.data', 'res')
Aktive Ergebnisse zeigen ✓ Einrichtungsname; inaktive zeigen ✗ Einrichtungsname.
Standardwert festlegen: search-default-api()
Verwenden Sie search-default-api() nach search-api(), um das Feld mit einer Standardauswahl vorzubefüllen, die von einem separaten API-Aufruf geladen wird (z. B. beim Bearbeiten eines vorhandenen Eintrags):
appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')
Benutzerdefiniertes Trennzeichen für select_multiple: search-default-separator()
Für select_multiple-Felder legen Sie fest, wie mehrere ausgewählte Werte in der gespeicherten Zeichenkette verbunden werden:
appearance: search-api(...) search-default-separator(' || ')
Standard-Trennzeichen ist ein Leerzeichen.
Unterstützte Fragetypen
| Fragetyp | Anwendungsfall |
|---|---|
select_one | Einzelauswahl aus Suchergebnissen |
select_multiple | Mehrfachauswahl aus Suchergebnissen |
text | Autovervollständigung — Interviewer tippt frei, kann aber einen Vorschlag auswählen |
Gespeicherte Antwortdaten verwenden
Der save_path speichert das vollständige API-Antwortobjekt unter dem angegebenen Namen. Andere Felder können es mit pulldata() referenzieren:
| type | name | label | calculation |
|---|---|---|---|
| select_one | facility | Einrichtung auswählen | search-api(..., 'facility_data') |
| calculate | facility_district | pulldata('facility_data', 'district') | |
| calculate | facility_type | pulldata('facility_data', 'type') |
Empfohlene Vorgehensweisen
- Stellen Sie sicher, dass Ihr API-Endpunkt innerhalb von 1–2 Sekunden antwortet — langsame APIs lassen die Suche träge wirken.
- Verwenden Sie
%__input__%impost_body, damit die API nur passende Ergebnisse zurückgibt, nicht den gesamten Datensatz. - Indizieren Sie das Suchfeld auf der Serverseite (z. B. Elasticsearch, Datenbankvolltextindex) für schnelle Antworten.
- Begrenzen Sie Ergebnisse auf 20–50 Einträge pro Abfrage — die Rückgabe von Tausenden von Ergebnissen untergräbt den Zweck der Suche.
- Fügen Sie eine Mindestlängenanforderung für die Eingabe in der API ein, um das Auslösen breiter Abfragen bei einzelnen Zeichen zu vermeiden.
Einschränkungen
- Die dynamische Suche erfordert Netzwerkkonnektivität — sie funktioniert nicht offline.
- Der Platzhalter
%__input__%wird unverändert eingefügt; bereinigen Sie Eingaben auf der Serverseite, um Injection-Angriffe zu verhindern. - Komplexe
@{func}-Anzeigeausdrücke können auf allen rtSurvey-Client-Versionen möglicherweise nur eingeschränkt unterstützt werden.