On this page
manage_search
API 호출
API 호출을 통해 설문이 외부 웹 서비스에서 데이터를 가져와 필드를 채우거나 답변을 검증할 수 있습니다.
API 호출 기능을 통해 설문 필드가 외부 서비스에 HTTP 요청을 보내고, 응답을 사용하여 계산된 값을 채우거나 사용자 입력을 검증할 수 있습니다. 이를 통해 데이터 수집 중 실시간 조회, ID 확인, 바코드 조회 및 기타 서버 측 검사가 가능합니다.
두 가지 함수가 있습니다:
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)
매개변수
| # | 매개변수 | 설명 |
|---|---|---|
| 1 | method | HTTP 메서드: 'GET' 또는 'POST' |
| 2 | url | API 엔드포인트 URL |
| 3 | allowed_auto | 필드에 도달할 때 자동으로 호출하려면 1; 수동 트리거 버튼을 요구하려면 0 |
| 4 | max_retry | 실패 시 최대 재시도 횟수 |
| 5 | no_overwrite | 필드에 이미 값이 있는 경우 유지하려면 1; 항상 덮어쓰려면 0 |
| 6 | extract_expr | 응답에서 원하는 값을 추출하는 JSONPath 표현식 (예: $.data.name) |
| 7 | timeout | 밀리초 단위의 요청 타임아웃 |
| 8 | lifetime | 다시 가져오기 전에 캐시된 응답이 유효한 기간 (밀리초) |
| 9 | response_q | 원시 HTTP 응답 코드를 저장할 필드의 이름 (예: ${response_status}) |
| 10 | call_type | (선택 사항) 특수 호출 모드: 'lazy-upload' 또는 'lazy-upload-multiple' |
| 11 | post_body | (선택 사항) POST 본문 문자열. ##fieldname##으로 양식 필드를 참조합니다 |
예시: 가구 ID로 가구를 조회하는 GET 요청
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| text | household_id | 가구 ID | ||
| calculate | hh_name | callapi | callapi('GET', concat('https://api.example.com/households/', ${household_id}), 1, 3, 0, '$.name', 10000, 0, '') | |
| note | hh_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
API 호출 통합을 활성화하려면 필드의 appearance 열에 callapi를 추가합니다:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | api_result | callapi | callapi('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)
매개변수
| # | 매개변수 | 설명 |
|---|---|---|
| 1 | method | HTTP 메서드: 'GET' 또는 'POST' |
| 2 | url | 확인 API 엔드포인트 |
| 3 | extract_expr | 응답에서 예상 값을 추출하는 JSONPath |
| 4 | match_expr | 추출된 값을 필드 값과 비교하는 표현식 (예: $.status = 'valid') |
| 5 | timeout | 밀리초 단위의 요청 타임아웃 |
| 6 | constraint_mode | 경고만을 위한 'soft'; 진행을 차단하는 'hard' |
| 7 | post_body | (선택 사항) ##fieldname## 치환이 있는 POST 본문 |
| 8 | message | (선택 사항) 오류 메시지. 다국어 지원: <en>Invalid!</en><vi>Không hợp lệ!</vi> |
예시: 자산 레지스트리에 대한 바코드 확인
| type | name | label | appearance | constraint | constraint_message |
|---|---|---|---|---|---|
| barcode | asset_code | 자산 바코드 스캔 | callapi-verify | callapi-verify('POST', 'https://api.example.com/assets/verify', '$.valid', ". = 'true'", 10000, 'hard', '{"code": "##asset_code##"}') | 자산이 레지스트리에 없습니다 |
Appearance: callapi-verify(...)
constraint에 callapi-verify()가 있는 필드의 appearance 열에는 이 필드가 API 검증을 사용한다는 것을 rtSurvey에 알리기 위해 callapi-verify(params) 또는 callapi-verify(dynamicParams)를 포함해야 합니다.
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##"}'))
모범 사례
- 합리적인
timeout을 설정합니다 (5000–15000ms) — 0 또는 매우 높은 값을 사용하지 마세요. - 조사원이 의식적으로 트리거해야 하는 검증의 경우
allowed_auto=0을 설정합니다 (예: ID 확인). - 필드가 나중에 편집될 수 있고 재가져오기가 수동 수정을 덮어쓰지 않도록 하려면
no_overwrite=1을 설정합니다. - 원시 응답 텍스트에 의존하기보다 특정 JSONPath로
extract_expr을 사용합니다. - 오프라인 모드에서 API 호출을 테스트합니다 — callapi는 우아하게 실패하고 오류를 표시하지만, 중요하지 않은 필드의 경우 양식이 여전히 완료될 수 있어야 합니다.
제한 사항
- 호출 시 네트워크 연결이 필요합니다 — 기기가 오프라인인 경우 호출이 실패합니다.
- API 응답은 JSON이어야 합니다 — XML 또는 일반 텍스트 응답은 추가 파싱이 필요합니다.
- 높은 호출 빈도 (예: 반복 인스턴스당 API 호출 하나)는 양식 탐색을 느리게 할 수 있습니다.
이 페이지가 도움이 되었나요?