Veçoria Call API lejon fushën e sondazhit të bëjë kërkesë HTTP ndaj shërbimit të jashtëm dhe të përdorë përgjigjen për të plotësuar vlerën e llogaritur ose validuar hyrjen e përdoruesit. Kjo mundëson kërkime në kohë reale, verifikimin e ID, kërkimet e barcode, dhe çdo kontroll tjetër nga ana e serverit gjatë mbledhjes së të dhënave.

Ekzistojnë dy funksione:

  • callapi() — merr vlerën nga API dhe e ruan në fushën calculate ose text
  • callapi-verify() — thërret API dhe bllokon progresin nëse përgjigja nuk përputhet me vlerën e pritur (përdoret në constraint)

callapi() — Merr dhe ruaj përgjigjen e API

Sintaksa

Vendoseni callapi() në kolonën calculation të fushës calculate ose text:

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

Parametrat

#ParametriPërshkrimi
1methodMetoda HTTP: 'GET' ose 'POST'
2urlURL e pikës fundore API
3allowed_auto1 për thirrje automatike kur arrihet fusha; 0 për kërkuar buton manual aktivizimi
4max_retryNumri maksimal i përpjekjeve për riprovim pas dështimit
5no_overwrite1 për të mbajtur vlerën ekzistuese nëse fusha ka tashmë vlerë; 0 për të mbishkruar gjithmonë
6extract_exprShprehja JSONPath për të nxjerrë vlerën e dëshiruar nga përgjigja (p.sh., $.data.name)
7timeoutAfati kohor i kërkesës në milisekonda
8lifetimeKohëzgjatja (ms) e cache-it të vlefshëm të përgjigjes para se të ri-merret
9response_qEmri i fushës për ruajtjen e kodit të paperpunuar HTTP të përgjigjes (p.sh., ${response_status})
10call_type(Opsionale) Mënyra speciale thirrjeje: 'lazy-upload' ose 'lazy-upload-multiple'
11post_body(Opsionale) Vargu i trupit POST. Referoni fushat e formularit me ##fieldname##

Shembull: Kërkesë GET për të kërkuar familje sipas ID

typenamelabelappearancecalculation
texthousehold_idID e familjes
calculatehh_namecallapicallapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '')
notehh_displayFamilja: ${hh_name}

Shembull: Kërkesë POST me trup JSON 

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

Në post_body, përdorni ##fieldname## për të injektuar vlerën aktuale të çdo fushe formulari.

Pamja: callapi

Shtoni callapi në kolonën appearance të fushës për të aktivizuar integrimin e thirrjes API:

typenamelabelappearancecalculation
calculateapi_resultcallapicallapi('GET', ...)

Kur allowed_auto është 0, rtSurvey tregon butonin “Merr” që numëruesi mund ta shtypë manualisht.

callapi-verify() — Validoni vlerën kundrejt API

callapi-verify() bllokon dorëzimin e fushës deri sa API të konfirmojë që vlera e futur është e vlefshme. Përdoreni në kolonën constraint.

Sintaksa 

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

Parametrat

#ParametriPërshkrimi
1methodMetoda HTTP: 'GET' ose 'POST'
2urlPika fundore API e verifikimit
3extract_exprJSONPath për të nxjerrë vlerën e pritur nga përgjigja
4match_exprShprehja që krahason vlerën e nxjerrë me vlerën e fushës (p.sh., $.status = 'valid')
5timeoutAfati kohor i kërkesës në milisekonda
6constraint_mode'soft' vetëm për paralajmërim; 'hard' për bllokimin e progresit
7post_body(Opsionale) Trupi POST me zëvendësimet ##fieldname##
8message(Opsionale) Mesazhi i gabimit. Mbështet shumë gjuhë: <en>Invalid!</en><vi>Không hợp lệ!</vi>

Shembull: Verifikoni barcode kundrejt regjistrit të aseteve

typenamelabelappearanceconstraintconstraint_message
barcodeasset_codeSkanoni barcodin e asetitcallapi-verifycallapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}')Aseti nuk u gjet në regjistër

Pamja: callapi-verify(...)

Kolona appearance në fushën me callapi-verify() në constraint duhet të përmbajë callapi-verify(params) ose callapi-verify(dynamicParams) për të sinjalizuar rtSurvey-t që kjo fushë përdor verifikimin API.

Përdorimi i të dhënave App API krahas callapi

Kombinoni callapi() me pulldata('app-api', 'user.token') për të injektuar tokenin e përdoruesit të autentifikuar në kërkesën tuaj API:

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

Praktikat më të mira

  1. Gjithmonë vendosni timeout të arsyeshëm (5000-15000 ms) — mos përdorni 0 ose vlera shumë të larta.
  2. Vendosni allowed_auto=0 për verifikime që numëruesi duhet t’i aktivizojë me vetëdije (p.sh., kontrollet e ID).
  3. Vendosni no_overwrite=1 kur fusha mund të editohet më vonë dhe nuk dëshironi ri-marrjen të mbishkruajë korrigjimet manuale.
  4. Përdorni extract_expr me JSONPath specifik në vend se të mbështeteni tek teksti i paperpunuar i përgjigjes.
  5. Testoni thirrjet API në modalitetin offline — callapi do të dështojë me elegancë dhe do të tregojë gabim, por formulari duhet të jetë akoma i plotësueshëm për fushat jo-kritike.

Kufizimet

  • Kërkon lidhje rrjeti në kohën e thirrjes — thirrjet do të dështojnë kur pajisja është offline.
  • Përgjigjet API duhet të jenë JSON — përgjigjet XML ose tekst i thjeshtë kërkojnë analizë shtesë.
  • Frekuenca e lartë e thirrjeve (p.sh., një thirrje API për çdo instancë përsëritjeje) mund të ngadalësojë navigimin e formularit.
A ishte e dobishme kjo faqe?