Η Δυναμική Αναζήτηση (γνωστή και ως Search API) επιτρέπει σε πεδίο select_one, select_multiple ή text να φορτώνει τις επιλογές του από απομακρυσμένη διαδικτυακή υπηρεσία κατά το χρόνο εκτέλεσης καθώς πληκτρολογεί ο απογραφέας. Αυτή είναι η σωστή προσέγγιση όταν η λίστα επιλογών σας είναι πολύ μεγάλη για να ενσωματωθεί σε αρχείο CSV, ενημερώνεται συχνά ή προέρχεται από ζωντανή βάση δεδομένων.

Εμφάνιση search-api()

Η δυναμική αναζήτηση διαμορφώνεται μέσω της στήλης appearance χρησιμοποιώντας τη συνάρτηση search-api():

  search-api(method, url, post_body, value_column, display, data_path, save_path)

Παράμετροι

ΠαράμετροςΠεριγραφή
methodΠάντα χρησιμοποιείτε 'POST'
urlΤο τελικό σημείο API για αναζήτηση
post_bodyΣώμα JSON που αποστέλλεται στο API. Χρησιμοποιήστε %__input__% ως placeholder για το τρέχον κείμενο αναζήτησης του απογραφέα
value_columnΤο κλειδί στο αντικείμενο απόκρισης που χρησιμοποιείται ως αποθηκευμένη τιμή
displayΤο κλειδί (ή πρότυπο) που χρησιμοποιείται ως ετικέτα που εμφανίζεται στο αναπτυσσόμενο μενού. Υποστηρίζει placeholders ##key## και εκφράσεις @{func}
data_pathJSONPath στον πίνακα αντικειμένων αποτελεσμάτων στην απόκριση (π.χ. $.data, $.hits.hits.*._source)
save_pathΌνομα υπό το οποίο αποθηκεύεται η ακατέργαστη απόκριση για χρήση από άλλα πεδία

Βασικό παράδειγμα

Αναζήτηση υγειονομικής μονάδας όπου ο απογραφέας πληκτρολογεί μέρος του ονόματος μονάδας:

typenamelabelappearance
select_onefacilityΕπιλογή υγειονομικής μονάδαςsearch-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data')

Το API λαμβάνει {"query": "nair"} όταν ο απογραφέας πληκτρολογεί “nair” και επιστρέφει:

  {
  "results": [
    {"id": "HF001", "name": "Nairobi Central Clinic"},
    {"id": "HF002", "name": "Nairobi West Hospital"}
  ]
}

Το αναπτυσσόμενο μενού εμφανίζει Nairobi Central Clinic και Nairobi West Hospital· η αποθηκευμένη τιμή είναι HF001 ή HF002.

Προχωρημένη μορφοποίηση εμφάνισης

Χρήση προτύπων ##key##

Εμφάνιση πολλαπλών πεδίων στην ετικέτα:

  search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')

Εμφανίζεται ως: Nairobi Central Clinic (Nairobi).

Χρήση εκφράσεων @{func}

Εφαρμογή υπό συνθήκη λογικής στην ετικέτα εμφάνισης:

  search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
  '@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
  '$.data', 'res')

Τα ενεργά αποτελέσματα εμφανίζουν ✓ Clinic Name· τα ανενεργά ✗ Clinic Name.

Ορισμός προεπιλεγμένης τιμής: search-default-api()

Χρησιμοποιήστε search-default-api() μετά το search-api() για προεκτύπωση πεδίου με προεπιλεγμένη επιλογή φορτωμένη από ξεχωριστή κλήση API (π.χ. κατά επεξεργασία υπάρχουσας εγγραφής):

  appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')

Προσαρμοσμένος διαχωριστής για select_multiple: search-default-separator()

Για πεδία select_multiple, καθορίστε πώς πολλαπλές επιλεγμένες τιμές συνενώνονται στην αποθηκευμένη συμβολοσειρά:

  appearance: search-api(...) search-default-separator(' || ')

Ο προεπιλεγμένος διαχωριστής είναι κενό.

Υποστηριζόμενοι τύποι ερωτήσεων

Τύπος ερώτησηςΠερίπτωση χρήσης
select_oneΜονή επιλογή από αποτελέσματα αναζήτησης
select_multipleΠολλαπλές επιλογές από αποτελέσματα αναζήτησης
textΑυτόματη συμπλήρωση — ο απογραφέας πληκτρολογεί ελεύθερα αλλά μπορεί να επιλέξει πρόταση

Χρήση αποθηκευμένων δεδομένων απόκρισης

Το save_path αποθηκεύει το πλήρες αντικείμενο απόκρισης API υπό το δοσμένο όνομα. Άλλα πεδία μπορούν να το αναφέρουν με pulldata():

typenamelabelcalculation
select_onefacilityΕπιλογή μονάδαςsearch-api(..., 'facility_data')
calculatefacility_districtpulldata('facility_data', 'district')
calculatefacility_typepulldata('facility_data', 'type')

Βέλτιστες πρακτικές

  1. Βεβαιωθείτε ότι το τελικό σημείο API αποκρίνεται εντός 1–2 δευτερολέπτων — τα αργά APIs κάνουν την αναζήτηση να φαίνεται αδέξια.
  2. Χρησιμοποιήστε %__input__% στο post_body ώστε το API να επιστρέφει μόνο αντιστοιχούμενα αποτελέσματα, όχι ολόκληρο το σύνολο δεδομένων.
  3. Ευρετηριάστε το πεδίο αναζήτησης στην πλευρά του διακομιστή (π.χ. Elasticsearch, ευρετήριο πλήρους κειμένου βάσης δεδομένων) για γρήγορες αποκρίσεις.
  4. Περιορίστε τα αποτελέσματα σε 20–50 στοιχεία ανά αναζήτηση — η επιστροφή χιλιάδων αποτελεσμάτων ακυρώνει τον σκοπό της αναζήτησης.
  5. Συμπεριλάβετε απαίτηση ελάχιστου μήκους εισόδου στο API για αποφυγή εκκίνησης ευρέων αναζητήσεων σε εισόδους ενός χαρακτήρα.

Περιορισμοί

  • Η δυναμική αναζήτηση απαιτεί συνδεσιμότητα δικτύου — δεν λειτουργεί εκτός σύνδεσης.
  • Το placeholder %__input__% εγχέεται ως έχει· εξυγιάνετε τις εισόδους στην πλευρά του διακομιστή για αποφυγή επιθέσεων έγχυσης.
  • Σύνθετες εκφράσεις εμφάνισης @{func} ενδέχεται να έχουν περιορισμένη υποστήριξη σε όλες τις εκδόσεις πελατών rtSurvey.
Ήταν χρήσιμη αυτή η σελίδα;