تتيح ميزة Call API لحقل الاستطلاع تقديم طلب HTTP لخدمة خارجية واستخدام الاستجابة لتعبئة قيمة محسوبة أو التحقق من مدخلات المستخدم. يُتيح ذلك عمليات البحث في الوقت الفعلي، والتحقق من الهوية، والبحث عن الرموز الشريطية، وأي فحص آخر من جانب الخادم أثناء جمع البيانات.

توجد دالتان:

  • 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'
2urlعنوان URL لنقطة نهاية API
3allowed_auto1 للاستدعاء تلقائياً عند الوصول إلى الحقل؛ 0 لطلب زر تشغيل يدوي
4max_retryالحد الأقصى لعدد محاولات إعادة المحاولة عند الفشل
5no_overwrite1 للاحتفاظ بالقيمة الموجودة إذا كان الحقل يحتوي على قيمة بالفعل؛ 0 للكتابة دائماً فوقها
6extract_exprتعبير JSONPath لاستخراج القيمة المطلوبة من الاستجابة (مثل $.data.name)
7timeoutمهلة الطلب بالميلي ثانية
8lifetimeالمدة (بالميلي ثانية) التي تبقى فيها الاستجابة المخبأة صالحة قبل إعادة الجلب
9response_qاسم حقل لتخزين رمز استجابة HTTP الخام (مثل ${response_status})
10call_type(اختياري) وضع الاستدعاء الخاص: 'lazy-upload' أو 'lazy-upload-multiple'
11post_body(اختياري) سلسلة جسم POST. استشر حقول النموذج باستخدام ##fieldname##

مثال: طلب GET للبحث عن أسرة بمعرّفها

typenamelabelappearancecalculation
texthousehold_idHousehold ID
calculatehh_namecallapicallapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '')
notehh_displayHousehold: ${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 زر “Fetch” يضغط عليه المعدِّد يدوياً.

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>

مثال: التحقق من رمز شريطي مقابل سجل الأصول

typenamelabelappearanceconstraintconstraint_message
barcodeasset_codeScan the asset barcodecallapi-verifycallapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}')Asset not found in registry

المظهر: callapi-verify(...)

يجب أن يحتوي عمود appearance على حقل مع callapi-verify() في القيد على callapi-verify(params) أو callapi-verify(dynamicParams) للإشارة إلى rtSurvey بأن هذا الحقل يستخدم التحقق عبر API.

استخدام بيانات App API جنباً إلى جنب مع callapi

ادمج callapi() مع pulldata('app-api', 'user.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 مللي ثانية) — لا تستخدم 0 أو قيماً عالية جداً.
  2. اضبط allowed_auto=0 للتحقق الذي يجب أن يُطلقه المعدِّد بوعي (مثل فحوصات الهوية).
  3. اضبط no_overwrite=1 عندما يمكن تعديل الحقل لاحقاً ولا تريد إعادة الجلب لتغطية التصحيحات اليدوية.
  4. استخدم extract_expr مع JSONPath محدد بدلاً من الاعتماد على نص الاستجابة الخام.
  5. اختبر استدعاءات API في وضع عدم الاتصال — سيفشل callapi بشكل رشيق ويُظهر خطأً، لكن يجب أن يظل النموذج قابلاً للإكمال للحقول غير الحرجة.

القيود

  • يتطلب اتصالاً بالشبكة وقت الاستدعاء — ستفشل الاستدعاءات عندما يكون الجهاز غير متصل.
  • يجب أن تكون استجابات API بتنسيق JSON — تتطلب استجابات XML أو النص العادي تحليلاً إضافياً.
  • يمكن لتكرار الاستدعاء العالي (مثل استدعاء API واحد لكل مثيل تكرار) إبطاء التنقل في النموذج.
هل كانت هذه الصفحة مفيدة؟