Dynamické vyhľadávanie
Dynamické vyhľadávanie načítava voľby zo vzdialeného API v reálnom čase ako anketár píše, umožňujúc veľké alebo často aktualizované datasety.
Dynamické vyhľadávanie (tiež nazývané Search API) umožňuje poľu select_one, select_multiple alebo text načítavať voľby zo vzdialenej webovej služby za behu ako anketár píše. Toto je správny prístup, keď je váš zoznam volieb príliš veľký na zahrnutie do CSV súboru, je často aktualizovaný alebo pochádza z živej databázy.
Vzhľad search-api()
Dynamické vyhľadávanie je nakonfigurované prostredníctvom stĺpca appearance pomocou funkcie search-api():
search-api(method, url, post_body, value_column, display, data_path, save_path)
Parametre
| Parameter | Popis |
|---|---|
method | Vždy použite 'POST' |
url | Koncový bod API na dotazovanie |
post_body | JSON telo odoslané do API. Použite %__input__% ako zástupný symbol pre aktuálny text vyhľadávania anketára |
value_column | Kľúč v objekte odpovede na použitie ako uložená hodnota |
display | Kľúč (alebo šablóna) na použitie ako popisok zobrazený v rozbaľovacom zozname. Podporuje zástupné symboly ##key## a výrazy @{func} |
data_path | JSONPath k poľu objektov výsledkov v odpovedi (napr. $.data, $.hits.hits.*._source) |
save_path | Názov, pod ktorým je uložená surová odpoveď na použitie inými poľami |
Základný príklad
Vyhľadávanie zdravotníckeho zariadenia, kde anketár píše časť názvu zariadenia:
| type | name | label | appearance |
|---|---|---|---|
| select_one | facility | Vyberte zdravotnícke zariadenie | search-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data') |
API prijme {"query": "nair"} keď anketár napíše „nair" a vráti:
{
"results": [
{"id": "HF001", "name": "Nairobi Central Clinic"},
{"id": "HF002", "name": "Nairobi West Hospital"}
]
}
Rozbaľovací zoznam zobrazí Nairobi Central Clinic a Nairobi West Hospital; uložená hodnota je HF001 alebo HF002.
Pokročilé formátovanie zobrazenia
Použitie šablón ##key##
Zobrazenie viacerých polí v popisku:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')
Zobrazené ako: Nairobi Central Clinic (Nairobi).
Použitie výrazov @{func}
Aplikovanie podmienenej logiky v popisku zobrazenia:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
'@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
'$.data', 'res')
Aktívne výsledky zobrazujú ✓ Názov kliniky; neaktívne zobrazujú ✗ Názov kliniky.
Nastavenie predvolenej hodnoty: search-default-api()
Použite search-default-api() po search-api() na predvyplnenie poľa predvolenou voľbou načítanou z oddelného volania API (napr. pri úprave existujúceho záznamu):
appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')
Vlastný oddeľovač pre select_multiple: search-default-separator()
Pre polia select_multiple uveďte, ako sú viaceré vybrané hodnoty spojené v uloženom reťazci:
appearance: search-api(...) search-default-separator(' || ')
Predvolený oddeľovač je medzera.
Podporované typy otázok
| Typ otázky | Prípad použitia |
|---|---|
select_one | Jeden výber z výsledkov vyhľadávania |
select_multiple | Viacero výberov z výsledkov vyhľadávania |
text | Automatické dopĺňanie — anketár píše voľne, ale môže vybrať návrh |
Používanie uložených dát odpovede
save_path ukladá celý objekt odpovede API pod daným názvom. Iné polia naň môžu odkazovať pomocou pulldata():
| type | name | label | calculation |
|---|---|---|---|
| select_one | facility | Vyberte zariadenie | search-api(..., 'facility_data') |
| calculate | facility_district | pulldata('facility_data', 'district') | |
| calculate | facility_type | pulldata('facility_data', 'type') |
Najlepšie postupy
- Uistite sa, že váš koncový bod API odpovedá do 1–2 sekúnd — pomalé API spôsobujú, že vyhľadávanie pôsobí neresponzívne.
- Použite
%__input__%vpost_body, aby API vracalo iba zodpovedajúce výsledky, nie celý dataset. - Indexujte pole vyhľadávania na strane servera (napr. Elasticsearch, databázový full-text index) pre rýchle odpovede.
- Obmedzte výsledky na 20–50 položiek na dotaz — vracanie tisícov výsledkov popiera účel vyhľadávania.
- Zahrňte požiadavku na minimálnu dĺžku vstupu v API, aby ste sa vyhli spúšťaniu širokých dotazov na vstupy s jedným znakom.
Obmedzenia
- Dynamické vyhľadávanie vyžaduje sieťové pripojenie — nefunguje offline.
- Zástupný symbol
%__input__%je vložený tak, ako je; sanitizujte vstupy na strane servera, aby ste predišli injection útokom. - Komplexné výrazy zobrazenia
@{func}môžu mať obmedzené fungovanie naprieč všetkými verziami klientov rtSurvey.