Dynamic Search
A Pesquisa Dinâmica carrega escolhas de uma API remota em tempo real à medida que o enumerador escreve, permitindo conjuntos de dados grandes ou frequentemente atualizados.
Pesquisa Dinâmica (também chamada Search API) permite que um campo select_one, select_multiple ou text carregue as suas escolhas de um serviço web remoto em tempo de execução à medida que o enumerador escreve. Esta é a abordagem correta quando a sua lista de escolhas é demasiado grande para incluir num ficheiro CSV, é atualizada com frequência ou vem de uma base de dados em tempo real.
Aparência search-api()
A pesquisa dinâmica é configurada através 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 da API a consultar |
post_body | Corpo JSON enviado para a API. Use %__input__% como marcador para o texto de pesquisa atual do enumerador |
value_column | A chave no objeto de resposta a usar como valor armazenado |
display | A chave (ou modelo) a usar como etiqueta mostrada no menu suspenso. Suporta marcadores ##key## e expressões @{func} |
data_path | JSONPath para o array de objetos de resultado na resposta (por ex., $.data, $.hits.hits.*._source) |
save_path | Um nome sob o qual a resposta bruta é guardada para uso por outros campos |
Exemplo básico
Uma pesquisa de unidade de saúde onde o enumerador escreve parte do nome da unidade:
| type | name | label | appearance |
|---|---|---|---|
| select_one | facility | Selecione a unidade 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 enumerador escreve “nair” e devolve:
{
"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
Usar modelos ##key##
Mostrar múltiplos campos na etiqueta:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')
Exibido como: Clínica Central de Nairobi (Nairobi).
Usar expressões @{func}
Aplicar lógica condicional na etiqueta de exibição:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
'@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
'$.data', 'res')
Os resultados ativos mostram ✓ Nome da Clínica; os inativos mostram ✗ Nome da Clínica.
Definir um valor padrão: search-default-api()
Use search-default-api() após search-api() para pré-preencher o campo com uma escolha padrão carregada de uma chamada de API separada (por ex., ao editar um registo 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 múltiplos valores selecionados são unidos na cadeia armazenada:
appearance: search-api(...) search-default-separator(' || ')
O separador padrão é um espaço.
Tipos de pergunta suportados
| Tipo de pergunta | Caso de uso |
|---|---|
select_one | Seleção única dos resultados de pesquisa |
select_multiple | Múltiplas seleções dos resultados de pesquisa |
text | Preenchimento automático — o enumerador escreve livremente mas pode selecionar uma sugestão |
Usar dados de resposta guardados
O save_path armazena o objeto de resposta completo da API sob o nome dado. Outros campos podem referenciá-lo com pulldata():
| type | name | label | calculation |
|---|---|---|---|
| select_one | facility | Selecione a unidade | search-api(..., 'facility_data') |
| calculate | facility_district | pulldata('facility_data', 'district') | |
| calculate | facility_type | pulldata('facility_data', 'type') |
Melhores Práticas
- Certifique-se de que o seu endpoint de API responde em 1–2 segundos — APIs lentas tornam a pesquisa sem resposta.
- Use
%__input__%nopost_bodypara que a API devolva apenas resultados correspondentes, não o conjunto de dados completo. - Indexe o campo de pesquisa no lado do servidor (por ex., Elasticsearch, índice de texto completo de base de dados) para respostas rápidas.
- Limite os resultados a 20–50 itens por consulta — devolver milhares de resultados derrota o propósito da pesquisa.
- Inclua um requisito de comprimento mínimo de entrada na API para evitar acionar consultas amplas em entradas de um único carácter.
Limitações
- A Pesquisa Dinâmica requer conectividade de rede — não funciona offline.
- O marcador
%__input__%é injetado tal 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 de cliente rtSurvey.