Busca dinâmica
A Busca dinâmica carrega opções de uma API remota em tempo real conforme o entrevistador digita, habilitando conjuntos de dados grandes ou frequentemente atualizados.
A Busca dinâmica (também chamada de Search API) permite que um campo select_one, select_multiple ou text carregue suas opções de um serviço web remoto em tempo de execução conforme o entrevistador digita. Esta é a abordagem correta quando sua lista de opções é grande demais para ser incluída em um arquivo CSV, é atualizada frequentemente ou vem de um banco de dados ativo.
Aparência search-api()
A busca dinâmica é configurada por meio da coluna appearance usando a função search-api():
search-api(method, url, post_body, value_column, display, data_path, save_path)
Parâmetros
| Parâmetro | Descrição |
|---|---|
method | Use sempre 'POST' |
url | O endpoint de API a ser consultado |
post_body | Corpo JSON enviado à API. Use %__input__% como espaço reservado para o texto de busca atual do entrevistador |
value_column | A chave no objeto de resposta a usar como valor armazenado |
display | A chave (ou modelo) a usar como rótulo mostrado no menu suspenso. Suporta espaços reservados ##key## e expressões @{func} |
data_path | JSONPath para o array de objetos de resultado na resposta (por exemplo, $.data, $.hits.hits.*._source) |
save_path | Um nome sob o qual a resposta bruta é salva para uso por outros campos |
Exemplo básico
Uma busca de estabelecimento de saúde onde o entrevistador digita parte do nome do estabelecimento:
| type | name | label | appearance |
|---|---|---|---|
| select_one | facility | Selecione o estabelecimento de saúde | search-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data') |
A API recebe {"query": "nair"} quando o entrevistador digita “nair” e retorna:
{
"results": [
{"id": "HF001", "name": "Clínica Central de Nairobi"},
{"id": "HF002", "name": "Hospital Oeste de Nairobi"}
]
}
O menu suspenso mostra Clínica Central de Nairobi e Hospital Oeste de Nairobi; o valor armazenado é HF001 ou HF002.
Formatação avançada de exibição
Usando modelos ##key##
Mostrar múltiplos campos no rótulo:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')
Exibido como: Clínica Central de Nairobi (Nairobi).
Usando expressões @{func}
Aplicar lógica condicional no rótulo de exibição:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
'@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
'$.data', 'res')
Resultados ativos mostram ✓ Nome da Clínica; inativos mostram ✗ Nome da Clínica.
Definindo um valor padrão: search-default-api()
Use search-default-api() após search-api() para pré-preencher o campo com uma opção padrão carregada de uma chamada de API separada (por exemplo, ao editar um registro existente):
appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')
Separador personalizado para select_multiple: search-default-separator()
Para campos select_multiple, especifique como os múltiplos valores selecionados são unidos na string armazenada:
appearance: search-api(...) search-default-separator(' || ')
O separador padrão é um espaço.
Tipos de perguntas suportados
| Tipo de pergunta | Caso de uso |
|---|---|
select_one | Seleção única a partir dos resultados da busca |
select_multiple | Múltiplas seleções a partir dos resultados da busca |
text | Preenchimento automático — o entrevistador digita livremente, mas pode selecionar uma sugestão |
Usando dados de resposta salvos
O save_path armazena o objeto de resposta completo da API sob o nome fornecido. Outros campos podem referenciá-lo com pulldata():
| type | name | label | calculation |
|---|---|---|---|
| select_one | facility | Selecionar estabelecimento | search-api(..., 'facility_data') |
| calculate | facility_district | pulldata('facility_data', 'district') | |
| calculate | facility_type | pulldata('facility_data', 'type') |
Práticas recomendadas
- Garanta que o endpoint de API responda em 1 a 2 segundos — APIs lentas tornam a busca sem resposta.
- Use
%__input__%nopost_bodypara que a API retorne apenas os resultados correspondentes, não o conjunto de dados completo. - Indexe o campo de busca no lado do servidor (por exemplo, Elasticsearch, índice de texto completo do banco de dados) para respostas rápidas.
- Limite os resultados a 20 a 50 itens por consulta — retornar milhares de resultados prejudica o propósito da busca.
- Inclua um requisito de comprimento mínimo de entrada na API para evitar acionar consultas amplas em entradas de um único caractere.
Limitações
- A Busca dinâmica requer conectividade de rede — não funciona off-line.
- O espaço reservado
%__input__%é injetado como está; sanitize as entradas no lado do servidor para evitar ataques de injeção. - Expressões de exibição
@{func}complexas podem ter suporte limitado em todas as versões do cliente rtSurvey.