Call API
Call API మీ సర్వే బాహ్య వెబ్ సేవ నుండి డేటా తీసుకోవడానికి మరియు ఫీల్డ్లు పాపులేట్ చేయడానికి లేదా సమాధానాలు ధృవీకరించడానికి ప్రతిస్పందనను ఉపయోగించడానికి అనుమతిస్తుంది.
Call API ఫీచర్ సర్వే ఫీల్డ్ని బాహ్య సేవకు HTTP అభ్యర్థన చేయడానికి మరియు లెక్కించిన విలువ పాపులేట్ చేయడానికి లేదా వినియోగదారు ఇన్పుట్ ధృవీకరించడానికి ప్రతిస్పందనను ఉపయోగించడానికి అనుమతిస్తుంది. ఇది రియల్-టైమ్ లుకప్లు, ID ధృవీకరణ, barcode లుకప్లు మరియు డేటా సేకరణ సమయంలో ఏదైనా ఇతర సర్వర్-వైపు తనిఖీలు ప్రారంభిస్తుంది.
రెండు ఫంక్షన్లు ఉన్నాయి:
callapi()— API నుండి విలువ తీసుకొనిcalculateలేదాtextఫీల్డ్లో నిల్వ చేస్తుందిcallapi-verify()— API ను కాల్ చేస్తుంది మరియు ప్రతిస్పందన ఆశించిన విలువతో సరిపోలకపోతే పురోగతిని నిరోధిస్తుంది (constraintలో ఉపయోగించబడుతుంది)
callapi() — API ప్రతిస్పందన తీసుకొని నిల్వ చేయడం
సింటాక్స్
calculate లేదా text ఫీల్డ్ యొక్క calculation కాలమ్లో callapi() ఉంచండి:
callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)
Parameters
| # | Parameter | వివరణ |
|---|---|---|
| 1 | method | HTTP పద్ధతి: 'GET' లేదా 'POST' |
| 2 | url | API endpoint URL |
| 3 | allowed_auto | ఫీల్డ్ చేరినప్పుడు స్వయంచాలకంగా కాల్ చేయడానికి 1; మాన్యువల్ ట్రిగర్ బటన్ అవసరమైతే 0 |
| 4 | max_retry | వైఫల్యంపై గరిష్ట పునఃప్రయత్న సంఖ్య |
| 5 | no_overwrite | ఫీల్డ్కు ఇప్పటికే విలువ ఉంటే ఉంచుకోవడానికి 1; ఎల్లప్పుడూ ఓవర్రైట్ చేయడానికి 0 |
| 6 | extract_expr | ప్రతిస్పందన నుండి కావలసిన విలువ సేకరించడానికి JSONPath వ్యక్తీకరణ (ఉదా. $.data.name) |
| 7 | timeout | అభ్యర్థన timeout మిల్లీసెకన్లలో |
| 8 | lifetime | క్యాష్ చేయబడిన ప్రతిస్పందన తిరిగి-తీసుకోవడానికి ముందు చెల్లుబాటు అయ్యే వ్యవధి (ms) |
| 9 | response_q | raw HTTP ప్రతిస్పందన కోడ్ నిల్వ చేయడానికి ఫీల్డ్ పేరు (ఉదా. ${response_status}) |
| 10 | call_type | (ఐచ్ఛికం) ప్రత్యేక కాల్ మోడ్: 'lazy-upload' లేదా 'lazy-upload-multiple' |
| 11 | post_body | (ఐచ్ఛికం) POST body స్ట్రింగ్. ఫారం ఫీల్డ్లను ##fieldname## తో సూచించండి |
ఉదాహరణ: ID ద్వారా గృహాన్ని చూడడానికి GET అభ్యర్థన
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| text | household_id | Household ID | ||
| calculate | hh_name | callapi | callapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '') | |
| note | hh_display | Household: ${hh_name} |
ఉదాహరణ: JSON body తో POST అభ్యర్థన
callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')
post_body లో, ఏదైనా ఫారం ఫీల్డ్ యొక్క ప్రస్తుత విలువ ఇంజెక్ట్ చేయడానికి ##fieldname## ఉపయోగించండి.
అపీరెన్స్: callapi
API కాల్ ఇంటిగ్రేషన్ ప్రారంభించడానికి ఫీల్డ్ యొక్క appearance కాలమ్కు callapi జోడించండి:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | api_result | callapi | callapi('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)
Parameters
| # | Parameter | వివరణ |
|---|---|---|
| 1 | method | HTTP పద్ధతి: 'GET' లేదా 'POST' |
| 2 | url | ధృవీకరణ API endpoint |
| 3 | extract_expr | ప్రతిస్పందన నుండి ఆశించిన విలువ సేకరించడానికి JSONPath |
| 4 | match_expr | సేకరించిన విలువను ఫీల్డ్ విలువతో పోల్చే వ్యక్తీకరణ (ఉదా. $.status = 'valid') |
| 5 | timeout | అభ్యర్థన timeout మిల్లీసెకన్లలో |
| 6 | constraint_mode | హెచ్చరిక మాత్రమే కోసం 'soft'; పురోగతిని నిరోధించడానికి 'hard' |
| 7 | post_body | (ఐచ్ఛికం) ##fieldname## ప్రత్యామ్నాయాలతో POST body |
| 8 | message | (ఐచ్ఛికం) లోపం సందేశం. బహుభాషా మద్దతు: <en>Invalid!</en><vi>Không hợp lệ!</vi> |
ఉదాహరణ: ఆస్తి రిజిస్ట్రీకి వ్యతిరేకంగా barcode ధృవీకరించడం
| type | name | label | appearance | constraint | constraint_message |
|---|---|---|---|---|---|
| barcode | asset_code | Scan the asset barcode | callapi-verify | callapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}') | Asset not found in registry |
అపీరెన్స్: callapi-verify(...)
constraint లో callapi-verify() ఉన్న ఫీల్డ్పై appearance కాలమ్లో callapi-verify(params) లేదా callapi-verify(dynamicParams) ఉండాలి.
callapi తో పాటు App API డేటా ఉపయోగించడం
ప్రమాణీకృత వినియోగదారు టోకెన్ను API అభ్యర్థనలో ఇంజెక్ట్ చేయడానికి callapi() ని pulldata('app-api', 'user.token') తో కలపండి:
callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))
ఉత్తమ పద్ధతులు
- సహేతుకమైన
timeout(5000–15000 ms) ఎల్లప్పుడూ సెట్ చేయండి — 0 లేదా చాలా అధిక విలువలు ఉపయోగించకండి. - గణికుడు స్పష్టంగా ట్రిగర్ చేయాల్సిన ధృవీకరణలకు (ఉదా. ID తనిఖీలు)
allowed_auto=0సెట్ చేయండి. - ఫీల్డ్ తర్వాత సవరించబడవచ్చు మరియు మాన్యువల్ దిద్దుబాట్లు ఓవర్రైట్ చేయాల్సి లేకపోతే
no_overwrite=1సెట్ చేయండి. - raw ప్రతిస్పందన టెక్స్ట్పై ఆధారపడటం కంటే నిర్దిష్ట JSONPath తో
extract_exprఉపయోగించండి. - ఆఫ్లైన్ మోడ్లో API కాల్లు పరీక్షించండి — callapi సున్నితంగా విఫలమవుతుంది మరియు లోపం చూపిస్తుంది, కానీ క్రిటికల్ కాని ఫీల్డ్లకు ఫారం ఇంకా పూర్తి చేయగలగాలి.
పరిమితులు
- కాల్ సమయంలో నెట్వర్క్ కనెక్టివిటీ అవసరం — పరికరం ఆఫ్లైన్లో ఉన్నప్పుడు కాల్లు విఫలమవుతాయి.
- API ప్రతిస్పందనలు JSON అయి ఉండాలి — XML లేదా plain-text ప్రతిస్పందనలకు అదనపు parsing అవసరం.
- అధిక కాల్ ఫ్రీక్వెన్సీ (ఉదా. ప్రతి రిపీట్ ఇన్స్టెన్స్కు ఒక API కాల్) ఫారం నావిగేషన్ నెమ్మదింపజేయవచ్చు.