동적 검색
동적 검색은 조사원이 입력하는 동안 실시간으로 원격 API에서 선택지를 로드하여 크거나 자주 업데이트되는 데이터셋을 가능하게 합니다.
동적 검색 (검색 API라고도 함)은 select_one, select_multiple 또는 text 필드가 조사원이 입력하는 동안 런타임에 원격 웹 서비스에서 선택지를 로드할 수 있도록 합니다. 선택지 목록이 CSV 파일에 번들로 묶기에 너무 크거나, 자주 업데이트되거나, 실시간 데이터베이스에서 제공될 때 적합한 방법입니다.
search-api() appearance
동적 검색은 search-api() 함수를 사용하여 appearance 열에서 구성됩니다:
search-api(method, url, post_body, value_column, display, data_path, save_path)
매개변수
| 매개변수 | 설명 |
|---|---|
method | 항상 'POST'를 사용합니다 |
url | 쿼리할 API 엔드포인트 |
post_body | API에 전송되는 JSON 본문. 조사원의 현재 검색 텍스트의 자리 표시자로 %__input__%를 사용합니다 |
value_column | 저장된 값으로 사용할 응답 객체의 키 |
display | 드롭다운에 표시되는 레이블로 사용할 키 (또는 템플릿). ##key## 자리 표시자와 @{func} 표현식을 지원합니다 |
data_path | 응답의 결과 객체 배열에 대한 JSONPath (예: $.data, $.hits.hits.*._source) |
save_path | 다른 필드에서 사용할 수 있도록 원시 응답이 저장되는 이름 |
기본 예시
조사원이 시설 이름의 일부를 입력하는 의료 시설 조회:
| type | name | label | appearance |
|---|---|---|---|
| select_one | facility | 의료 시설 선택 | search-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data') |
조사원이 “나이” 입력 시 API는 {"query": "나이"}를 수신하고 반환합니다:
{
"results": [
{"id": "HF001", "name": "나이로비 중앙 클리닉"},
{"id": "HF002", "name": "나이로비 웨스트 병원"}
]
}
드롭다운에 나이로비 중앙 클리닉과 나이로비 웨스트 병원이 표시됩니다; 저장된 값은 HF001 또는 HF002입니다.
고급 표시 형식
##key## 템플릿 사용
레이블에 여러 필드 표시:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')
표시 형식: 나이로비 중앙 클리닉 (나이로비).
@{func} 표현식 사용
표시 레이블에서 조건부 논리 적용:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
'@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
'$.data', 'res')
활성 결과는 ✓ 클리닉 이름으로, 비활성은 ✗ 클리닉 이름으로 표시됩니다.
기본값 설정: search-default-api()
search-api() 뒤에 search-default-api()를 사용하여 별도의 API 호출에서 로드된 기본 선택지로 필드를 미리 채웁니다 (예: 기존 레코드 편집 시):
appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')
select_multiple에 대한 사용자 정의 구분자: search-default-separator()
select_multiple 필드의 경우 여러 선택된 값이 저장된 문자열에서 연결되는 방식을 지정합니다:
appearance: search-api(...) search-default-separator(' || ')
기본 구분자는 공백입니다.
지원되는 질문 유형
| 질문 유형 | 사용 사례 |
|---|---|
select_one | 검색 결과에서 단일 선택 |
select_multiple | 검색 결과에서 다중 선택 |
text | 자동 완성 — 조사원이 자유롭게 입력하지만 제안을 선택할 수 있음 |
저장된 응답 데이터 사용
save_path는 전체 API 응답 객체를 지정된 이름 아래에 저장합니다. 다른 필드는 pulldata()로 참조할 수 있습니다:
| type | name | label | calculation |
|---|---|---|---|
| select_one | facility | 시설 선택 | search-api(..., 'facility_data') |
| calculate | facility_district | pulldata('facility_data', 'district') | |
| calculate | facility_type | pulldata('facility_data', 'type') |
모범 사례
- API 엔드포인트가 1–2초 내에 응답하는지 확인합니다 — 느린 API는 검색이 반응하지 않는 것처럼 느껴지게 합니다.
- API가 전체 데이터셋이 아닌 일치하는 결과만 반환하도록
post_body에%__input__%를 사용합니다. - 빠른 응답을 위해 서버 측 (예: Elasticsearch, 데이터베이스 전체 텍스트 인덱스)에서 검색 필드를 인덱싱합니다.
- 쿼리당 결과를 20–50개로 제한합니다 — 수천 개의 결과를 반환하면 검색의 목적이 무의미해집니다.
- 단일 문자 입력으로 광범위한 쿼리가 트리거되는 것을 방지하기 위해 API에서 최소 입력 길이 요구 사항을 포함합니다.
제한 사항
- 동적 검색은 네트워크 연결이 필요합니다 — 오프라인에서는 작동하지 않습니다.
%__input__%자리 표시자는 그대로 삽입됩니다; 인젝션 공격을 방지하기 위해 서버 측에서 입력을 정제합니다.- 복잡한
@{func}표시 표현식은 모든 rtSurvey 클라이언트 버전에서 지원이 제한될 수 있습니다.