Call API
Call API memungkinkan survei Anda mengambil data dari layanan web eksternal dan menggunakan respons untuk mengisi bidang atau memvalidasi jawaban.
Fitur Call API memungkinkan bidang survei membuat permintaan HTTP ke layanan eksternal dan menggunakan respons untuk mengisi nilai yang dihitung atau memvalidasi input pengguna. Ini memungkinkan pencarian real-time, verifikasi ID, pencarian barcode, dan pemeriksaan sisi server lainnya selama pengumpulan data.
Ada dua fungsi:
callapi()— mengambil nilai dari API dan menyimpannya dalam bidangcalculateatautextcallapi-verify()— memanggil API dan memblokir kemajuan jika respons tidak cocok dengan nilai yang diharapkan (digunakan dalamconstraint)
callapi() — Ambil dan simpan respons API
Sintaks
Tempatkan callapi() dalam kolom calculation dari bidang calculate atau text:
callapi(method, url, allowed_auto, max_retry, no_overwrite, extract_expr, timeout, lifetime, response_q, call_type, post_body)
Parameter
| # | Parameter | Deskripsi |
|---|---|---|
| 1 | method | Metode HTTP: 'GET' atau 'POST' |
| 2 | url | URL endpoint API |
| 3 | allowed_auto | 1 untuk memanggil secara otomatis ketika bidang tercapai; 0 untuk memerlukan tombol pemicu manual |
| 4 | max_retry | Jumlah maksimum percobaan ulang saat gagal |
| 5 | no_overwrite | 1 untuk mempertahankan nilai yang ada jika bidang sudah memiliki nilai; 0 untuk selalu menimpa |
| 6 | extract_expr | Ekspresi JSONPath untuk mengekstrak nilai yang diinginkan dari respons (misalnya, $.data.name) |
| 7 | timeout | Batas waktu permintaan dalam milidetik |
| 8 | lifetime | Berapa lama (ms) respons yang di-cache tetap valid sebelum diambil ulang |
| 9 | response_q | Nama bidang untuk menyimpan kode respons HTTP mentah (misalnya, ${response_status}) |
| 10 | call_type | (Opsional) Mode panggilan khusus: 'lazy-upload' atau 'lazy-upload-multiple' |
| 11 | post_body | (Opsional) String body POST. Referensikan bidang formulir dengan ##fieldname## |
Contoh: Permintaan GET untuk mencari rumah tangga berdasarkan ID
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| text | household_id | ID Rumah Tangga | ||
| calculate | hh_name | callapi | callapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '') | |
| note | hh_display | Rumah Tangga: ${hh_name} |
Contoh: Permintaan POST dengan body JSON
callapi('POST', 'https://api.example.com/lookup', 1, 2, 0, '$.result.value', 15000, 0, '', '', '{"id": "##household_id##"}')
Dalam post_body, gunakan ##fieldname## untuk menyuntikkan nilai saat ini dari bidang formulir mana pun.
Appearance: callapi
Tambahkan callapi ke kolom appearance bidang untuk mengaktifkan integrasi panggilan API:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | api_result | callapi | callapi('GET', ...) |
Ketika allowed_auto adalah 0, rtSurvey menampilkan tombol “Fetch” yang enumerator ketuk secara manual.
callapi-verify() — Validasi nilai terhadap API
callapi-verify() memblokir pengiriman bidang sampai API mengkonfirmasi nilai yang dimasukkan valid. Gunakan dalam kolom constraint.
Sintaks
callapi-verify(method, url, extract_expr, match_expr, timeout, constraint_mode, post_body, message)
Parameter
| # | Parameter | Deskripsi |
|---|---|---|
| 1 | method | Metode HTTP: 'GET' atau 'POST' |
| 2 | url | Endpoint API verifikasi |
| 3 | extract_expr | JSONPath untuk mengekstrak nilai yang diharapkan dari respons |
| 4 | match_expr | Ekspresi yang membandingkan nilai yang diekstrak dengan nilai bidang (misalnya, $.status = 'valid') |
| 5 | timeout | Batas waktu permintaan dalam milidetik |
| 6 | constraint_mode | 'soft' hanya untuk peringatan; 'hard' untuk memblokir kemajuan |
| 7 | post_body | (Opsional) Body POST dengan substitusi ##fieldname## |
| 8 | message | (Opsional) Pesan kesalahan. Mendukung multi-bahasa: <en>Invalid!</en><vi>Không hợp lệ!</vi> |
Contoh: Verifikasi barcode terhadap registri aset
| type | name | label | appearance | constraint | constraint_message |
|---|---|---|---|---|---|
| barcode | asset_code | Pindai barcode aset | callapi-verify | callapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}') | Aset tidak ditemukan dalam registri |
Appearance: callapi-verify(...)
Kolom appearance pada bidang dengan callapi-verify() dalam constraint harus berisi callapi-verify(params) atau callapi-verify(dynamicParams) untuk menandai kepada rtSurvey bahwa bidang ini menggunakan verifikasi API.
Menggunakan data App API bersama callapi
Gabungkan callapi() dengan pulldata('app-api', 'user.token') untuk menyuntikkan token pengguna yang terautentikasi ke dalam permintaan API Anda:
callapi('POST', 'https://api.example.com/data', 1, 2, 0, '$.value', 10000, 0, '', '',
concat('{"token":"', pulldata('app-api','user.token'), '","id":"##item_id##"}'))
Praktik Terbaik
- Selalu tetapkan
timeoutyang wajar (5000–15000 ms) — jangan gunakan 0 atau nilai yang sangat tinggi. - Tetapkan
allowed_auto=0untuk verifikasi yang harus dipicu enumerator secara sadar (misalnya, pemeriksaan ID). - Tetapkan
no_overwrite=1ketika bidang mungkin diedit nanti dan Anda tidak ingin pengambilan ulang menimpa koreksi manual. - Gunakan
extract_exprdengan JSONPath spesifik daripada mengandalkan teks respons mentah. - Uji panggilan API dalam mode offline — callapi akan gagal dengan anggun dan menampilkan kesalahan, tetapi formulir harus tetap dapat diselesaikan untuk bidang yang tidak kritis.
Keterbatasan
- Memerlukan konektivitas jaringan saat panggilan — panggilan akan gagal ketika perangkat offline.
- Respons API harus berupa JSON — respons XML atau teks biasa memerlukan penguraian tambahan.
- Frekuensi panggilan yang tinggi (misalnya, satu panggilan API per instans pengulangan) dapat memperlambat navigasi formulir.