Η δυνατότητα Call API επιτρέπει σε ένα πεδίο έρευνας να κάνει αίτημα HTTP σε εξωτερική υπηρεσία και να χρησιμοποιεί την απόκριση για συμπλήρωση υπολογισμένης τιμής ή επικύρωση εισόδου χρήστη. Αυτό επιτρέπει αναζητήσεις πραγματικού χρόνου, επαλήθευση ID, αναζητήσεις barcode και οποιονδήποτε άλλο έλεγχο στην πλευρά του διακομιστή κατά τη συλλογή δεδομένων.

Υπάρχουν δύο συναρτήσεις:

  • callapi() — ανακτά μια τιμή από ένα API και την αποθηκεύει σε πεδίο calculate ή text
  • callapi-verify() — καλεί ένα API και εμποδίζει την πρόοδο εάν η απόκριση δεν ταιριάζει με την αναμενόμενη τιμή (χρησιμοποιείται σε constraint)

callapi() — Ανάκτηση και αποθήκευση απόκρισης API

Σύνταξη

Τοποθετήστε callapi() στη στήλη calculation ενός πεδίου calculate ή text:

  callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)

Παράμετροι

#ΠαράμετροςΠεριγραφή
1methodΜέθοδος HTTP: 'GET' ή 'POST'
2urlURL τελικού σημείου API
3allowed_auto1 για αυτόματη κλήση όταν φτάνει το πεδίο· 0 για απαίτηση χειροκίνητου κουμπιού
4max_retryΜέγιστος αριθμός επαναπροσπαθειών σε αποτυχία
5no_overwrite1 για διατήρηση υπάρχουσας τιμής εάν το πεδίο έχει ήδη μία· 0 για πάντα αντικατάσταση
6extract_exprΈκφραση JSONPath για εξαγωγή επιθυμητής τιμής από την απόκριση (π.χ. $.data.name)
7timeoutΧρονικό όριο αιτήματος σε χιλιοστά δευτερολέπτου
8lifetimeΧρόνος (ms) που παραμένει έγκυρη η αποθηκευμένη απόκριση πριν επαναφόρτωση
9response_qΌνομα πεδίου για αποθήκευση ακατέργαστου κωδικού HTTP απόκρισης (π.χ. ${response_status})
10call_type(Προαιρετικό) Ειδική λειτουργία κλήσης: 'lazy-upload' ή 'lazy-upload-multiple'
11post_body(Προαιρετικό) Συμβολοσειρά σώματος POST. Αναφορά πεδίων φόρμας με ##fieldname##

Παράδειγμα: Αίτημα GET για αναζήτηση νοικοκυριού βάσει ID

typenamelabelappearancecalculation
texthousehold_idID νοικοκυριού
calculatehh_namecallapicallapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '')
notehh_displayΝοικοκυριό: ${hh_name}

Παράδειγμα: Αίτημα POST με σώμα JSON 

  callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')

Στο post_body, χρησιμοποιήστε ##fieldname## για έγχυση της τρέχουσας τιμής οποιουδήποτε πεδίου φόρμας.

Εμφάνιση: callapi

Προσθέστε callapi στη στήλη appearance του πεδίου για ενεργοποίηση της ενοποίησης κλήσης API:

typenamelabelappearancecalculation
calculateapi_resultcallapicallapi('GET', ...)

Όταν allowed_auto είναι 0, το rtSurvey εμφανίζει κουμπί “Ανάκτηση” που πατά χειροκίνητα ο απογραφέας.

callapi-verify() — Επικύρωση τιμής έναντι API

Το callapi-verify() εμποδίζει την υποβολή πεδίου μέχρι ένα API να επιβεβαιώσει ότι η εισαχθείσα τιμή είναι έγκυρη. Χρησιμοποιείτε το στη στήλη constraint.

Σύνταξη 

  callapi-verify(method, url, extract_expr, match_expr, timeout, constraint_mode, post_body, message)

Παράμετροι

#ΠαράμετροςΠεριγραφή
1methodΜέθοδος HTTP: 'GET' ή 'POST'
2urlΤελικό σημείο API επαλήθευσης
3extract_exprJSONPath για εξαγωγή αναμενόμενης τιμής από την απόκριση
4match_exprΈκφραση σύγκρισης εξαχθείσας τιμής με την τιμή πεδίου (π.χ. $.status = 'valid')
5timeoutΧρονικό όριο αιτήματος σε χιλιοστά δευτερολέπτου
6constraint_mode'soft' μόνο για προειδοποίηση· 'hard' για εμπόδιο προόδου
7post_body(Προαιρετικό) Σώμα POST με υποκαταστάσεις ##fieldname##
8message(Προαιρετικό) Μήνυμα σφάλματος. Υποστηρίζει πολλές γλώσσες: <en>Invalid!</en><vi>Không hợp lệ!</vi>

Παράδειγμα: Επαλήθευση barcode έναντι μητρώου στοιχείων

typenamelabelappearanceconstraintconstraint_message
barcodeasset_codeΣαρώστε το barcode στοιχείουcallapi-verifycallapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}')Το στοιχείο δεν βρέθηκε στο μητρώο

Εμφάνιση: callapi-verify(...)

Η στήλη appearance σε πεδίο με callapi-verify() στο constraint πρέπει να περιέχει callapi-verify(params) ή callapi-verify(dynamicParams) για να σηματοδοτήσει στο rtSurvey ότι αυτό το πεδίο χρησιμοποιεί επαλήθευση API.

Χρήση δεδομένων App API μαζί με callapi

Συνδυάστε callapi() με pulldata('app-api', 'user.token') για έγχυση του token του επαληθευμένου χρήστη στο αίτημα API:

  callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
  concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))

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

  1. Πάντα ορίζετε λογικό timeout (5000–15000 ms) — μη χρησιμοποιείτε 0 ή πολύ υψηλές τιμές.
  2. Ορίστε allowed_auto=0 για επαληθεύσεις που ο απογραφέας πρέπει να ενεργοποιήσει συνειδητά (π.χ. έλεγχοι ID).
  3. Ορίστε no_overwrite=1 όταν το πεδίο μπορεί να επεξεργαστεί αργότερα και δεν θέλετε η επαναφόρτωση να αντικαταστήσει χειροκίνητες διορθώσεις.
  4. Χρησιμοποιήστε extract_expr με συγκεκριμένο JSONPath αντί να βασίζεστε σε ακατέργαστο κείμενο απόκρισης.
  5. Δοκιμάστε κλήσεις API σε λειτουργία εκτός σύνδεσης — το callapi θα αποτύχει ευγενικά και θα εμφανίσει σφάλμα, αλλά η φόρμα θα πρέπει να εξακολουθεί να μπορεί να συμπληρωθεί για μη κρίσιμα πεδία.

Περιορισμοί

  • Απαιτεί συνδεσιμότητα δικτύου κατά τη διάρκεια της κλήσης — οι κλήσεις αποτυγχάνουν όταν η συσκευή είναι εκτός σύνδεσης.
  • Οι αποκρίσεις API πρέπει να είναι JSON — οι αποκρίσεις XML ή απλού κειμένου απαιτούν πρόσθετη ανάλυση.
  • Υψηλή συχνότητα κλήσεων (π.χ. μία κλήση API ανά παρουσία επανάληψης) μπορεί να επιβραδύνει την πλοήγηση φόρμας.
Ήταν χρήσιμη αυτή η σελίδα;