Call API 功能让调查字段能够向外部服务发起 HTTP 请求，并使用响应填充计算值或验证用户输入。这实现了数据收集期间的实时查找、ID 验证、条形码查找以及任何其他服务器端检查。

有两个函数：

  • callapi() — 从 API 获取值并将其存储在 calculate 或 text 字段中
  • callapi-verify() — 调用 API，如果响应与预期值不匹配则阻止进度（用于 constraint）

callapi() — 获取并存储 API 响应

语法

将 callapi() 放在 calculate 或 text 字段的 calculation 列中：

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

参数

#参数描述
1methodHTTP 方法：'GET' 或 'POST'
2urlAPI 端点 URL
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 请求按 ID 查询家庭

typenamelabelappearancecalculation
texthousehold_id家庭 ID
calculatehh_namecallapicallapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '')
notehh_display家庭：${hh_name}

示例：带 JSON 请求体的 POST 请求 

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

在 post_body 中，使用 ##fieldname## 注入任何表单字段的当前值。

Appearance：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)

参数

#参数描述
1methodHTTP 方法：'GET' 或 'POST'
2url验证 API 端点
3extract_expr从响应中提取预期值的 JSONPath
4match_expr将提取的值与字段值进行比较的表达式（例如，$.status = 'valid'）
5timeout请求超时（毫秒）
6constraint_mode'soft' 表示仅警告；'hard' 表示阻止进度
7post_body（可选） 带 ##fieldname## 替换的 POST 请求体
8message（可选） 错误消息。支持多语言：<en>Invalid!</en><vi>Không hợp lệ!</vi>

示例：根据资产注册表验证条形码

typenamelabelappearanceconstraintconstraint_message
barcodeasset_code扫描资产条形码callapi-verifycallapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}')资产未在注册表中找到

Appearance：callapi-verify(...)

在 constraint 中含 callapi-verify() 的字段的 appearance 列应包含 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. 对于枚举员应有意识触发的验证（例如，ID 检查），设置 allowed_auto=0。
  3. 当字段可能稍后编辑且您不希望重新获取覆盖手动更正时，设置 no_overwrite=1。
  4. 使用具体的 JSONPath 的 extract_expr，而不是依赖原始响应文本。
  5. 在离线模式下测试 API 调用——callapi 将优雅地失败并显示错误，但对于非关键字段，表单仍应可完成。

限制

  • 在调用时需要网络连接——设备离线时调用将失败。
  • API 响应必须是 JSON——XML 或纯文本响应需要额外解析。
  • 高调用频率（例如，每个重复实例一个 API 调用）可能会降低表单导航速度。
此页面有帮助吗？