Dinaminė paieška
Dinaminė paieška įkelia pasirinkimus iš nuotolinės API realiuoju laiku, kai surašytojas rašo, įgalinant didelius ar dažnai atnaujinamais duomenų rinkinius.
Dinaminė paieška (taip pat vadinama Paieškos API) leidžia select_one, select_multiple arba text laukui įkelti savo pasirinkimus iš nuotolinės žiniatinklio paslaugos vykdymo metu, kai surašytojas rašo. Tai tinkamas metodas, kai jūsų pasirinkimų sąrašas yra per didelis, kad jį būtų galima įtraukti į CSV failą, yra dažnai atnaujinamas arba ateina iš gyvos duomenų bazės.
search-api() išvaizda
Dinaminė paieška konfigūruojama per stulpelį appearance naudojant funkciją search-api():
search-api(method, url, post_body, value_column, display, data_path, save_path)
Parametrai
| Parametras | Aprašymas |
|---|---|
method | Visada naudokite 'POST' |
url | API galiuklio URL užklausai |
post_body | JSON turinys, siunčiamas API. Naudokite %__input__% kaip vietos laikiklį dabartiniam surašytojo paieškos tekstui |
value_column | Atsakymo objekto raktas, naudojamas kaip saugoma reikšmė |
display | Raktas (arba šablonas), naudojamas kaip etiketė, rodoma išskleidžiamajame sąraše. Palaiko ##raktas## vietos laikiklius ir @{func} išraiškas |
data_path | JSONPath į rezultatų objektų masyvą atsakyme (pvz., $.data, $.hits.hits.*._source) |
save_path | Pavadinimas, po kuriuo saugomas neapdorotas atsakymas, kad galėtų juo naudotis kiti laukai |
Pagrindinis pavyzdys
Sveikatos įstaigos paieška, kai surašytojas įveda dalį įstaigos pavadinimo:
| type | name | label | appearance |
|---|---|---|---|
| select_one | facility | Pasirinkite sveikatos įstaigą | search-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data') |
API gauna {"query": "nair"}, kai surašytojas įveda „nair", ir grąžina:
{
"results": [
{"id": "HF001", "name": "Nairobi Central Clinic"},
{"id": "HF002", "name": "Nairobi West Hospital"}
]
}
Išskleidžiamajame meniu rodoma Nairobi Central Clinic ir Nairobi West Hospital; saugoma reikšmė yra HF001 arba HF002.
Pažangus rodinio formatavimas
##raktas## šablonų naudojimas
Rodykite kelis laukus etiketėje:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')
Rodoma kaip: Nairobi Central Clinic (Nairobi).
@{func} išraiškų naudojimas
Taikykite sąlyginę logiką rodinio etiketėje:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
'@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
'$.data', 'res')
Aktyvūs rezultatai rodo ✓ Klinikos pavadinimas; neaktyvūs — ✗ Klinikos pavadinimas.
Numatytosios reikšmės nustatymas: search-default-api()
Naudokite search-default-api() po search-api(), kad iš anksto užpildytumėte lauką su numatytąja pasirinkimo reikšme, įkelta iš atskiro API skambučio (pvz., redaguojant esamą įrašą):
appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')
Pasirinktinis atskyriklias select_multiple: search-default-separator()
select_multiple laukams nurodykite, kaip kelios pasirinktos reikšmės sujungiamos saugomoje eilutėje:
appearance: search-api(...) search-default-separator(' || ')
Numatytasis atskyriklias yra tarpas.
Palaikomi klausimų tipai
| Klausimo tipas | Naudojimo atvejis |
|---|---|
select_one | Vienas pasirinkimas iš paieškos rezultatų |
select_multiple | Keli pasirinkimai iš paieškos rezultatų |
text | Automatinis pildymas — surašytojas rašo laisvai, tačiau gali pasirinkti pasiūlymą |
Saugomo atsakymo duomenų naudojimas
save_path saugo pilną API atsakymo objektą nurodytu pavadinimu. Kiti laukai gali jį pasiekti naudodami pulldata():
| type | name | label | calculation |
|---|---|---|---|
| select_one | facility | Pasirinkite įstaigą | search-api(..., 'facility_data') |
| calculate | facility_district | pulldata('facility_data', 'district') | |
| calculate | facility_type | pulldata('facility_data', 'type') |
Geriausios praktikos
- Užtikrinkite, kad jūsų API galiuklis reaguoja per 1–2 sekundes — lėtos API padaro paiešką nejautrią.
- Naudokite
%__input__%post_body, kad API grąžintų tik atitinkančius rezultatus, o ne visą duomenų rinkinį. - Indeksuokite paieškos lauką serveryje (pvz., Elasticsearch, duomenų bazės visateksčio teksto indeksas) gretiems atsakymams.
- Ribokite rezultatus iki 20–50 elementų vienai užklausai — tūkstančių rezultatų grąžinimas naikina paieškos tikslą.
- Įtraukite minimalios įvesties ilgio reikalavimą API, kad išvengtumėte platių užklausų aktyvavimo vieno simbolio įvestimis.
Apribojimai
- Dinaminei paieškai reikalingas tinklo ryšys — ji neveikia neprisijungus.
- Vietos laikiklis
%__input__%įterpiamas tokiame pavidale; sanitizuokite įvestis serveryje, kad išvengtumėte injekcijos atakų. - Sudėtingos
@{func}rodymo išraiškos gali turėti ribotą palaikymą visose rtSurvey kliento versijose.