Búsqueda dinámica
La búsqueda dinámica carga opciones desde una API remota en tiempo real mientras el encuestador escribe, permitiendo conjuntos de datos grandes o actualizados con frecuencia.
La Búsqueda dinámica (también llamada Search API) permite que un campo select_one, select_multiple o text cargue sus opciones desde un servicio web remoto en tiempo real mientras el encuestador escribe. Este es el enfoque correcto cuando su lista de opciones es demasiado grande para incluirla en un archivo CSV, se actualiza con frecuencia, o proviene de una base de datos activa.
Apariencia search-api()
La búsqueda dinámica se configura a través de la columna appearance usando la función search-api():
search-api(method, url, post_body, value_column, display, data_path, save_path)
Parámetros
| Parámetro | Descripción |
|---|---|
method | Siempre use 'POST' |
url | El endpoint de la API a consultar |
post_body | Cuerpo JSON enviado a la API. Use %__input__% como marcador de posición para el texto de búsqueda actual del encuestador |
value_column | La clave en el objeto de respuesta que se usará como valor almacenado |
display | La clave (o plantilla) que se usará como etiqueta mostrada en el menú desplegable. Admite marcadores ##key## y expresiones @{func} |
data_path | JSONPath al array de objetos de resultado en la respuesta (p. ej., $.data, $.hits.hits.*._source) |
save_path | Un nombre bajo el cual se guarda la respuesta sin procesar para uso por otros campos |
Ejemplo básico
Una búsqueda de establecimientos de salud donde el encuestador escribe parte del nombre del establecimiento:
| type | name | label | appearance |
|---|---|---|---|
| select_one | facility | Seleccione el establecimiento de salud | search-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data') |
La API recibe {"query": "nair"} cuando el encuestador escribe “nair” y devuelve:
{
"results": [
{"id": "HF001", "name": "Nairobi Central Clinic"},
{"id": "HF002", "name": "Nairobi West Hospital"}
]
}
El menú desplegable muestra Nairobi Central Clinic y Nairobi West Hospital; el valor almacenado es HF001 o HF002.
Formato de visualización avanzado
Uso de plantillas ##key##
Mostrar múltiples campos en la etiqueta:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')
Se muestra como: Nairobi Central Clinic (Nairobi).
Uso de expresiones @{func}
Aplicar lógica condicional en la etiqueta de visualización:
search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
'@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
'$.data', 'res')
Los resultados activos muestran ✓ Nombre de la clínica; los inactivos muestran ✗ Nombre de la clínica.
Establecer un valor predeterminado: search-default-api()
Use search-default-api() después de search-api() para precargar el campo con una opción predeterminada cargada desde una llamada API separada (p. ej., al editar un 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 cómo se unen múltiples valores seleccionados en la cadena almacenada:
appearance: search-api(...) search-default-separator(' || ')
El separador predeterminado es un espacio.
Tipos de pregunta admitidos
| Tipo de pregunta | Caso de uso |
|---|---|
select_one | Selección única de los resultados de búsqueda |
select_multiple | Selecciones múltiples de los resultados de búsqueda |
text | Autocompletado: el encuestador escribe libremente pero puede seleccionar una sugerencia |
Uso de datos de respuesta guardados
El save_path almacena el objeto de respuesta completo de la API bajo el nombre dado. Otros campos pueden referenciarlo con pulldata():
| type | name | label | calculation |
|---|---|---|---|
| select_one | facility | Seleccionar establecimiento | search-api(..., 'facility_data') |
| calculate | facility_district | pulldata('facility_data', 'district') | |
| calculate | facility_type | pulldata('facility_data', 'type') |
Mejores prácticas
- Asegúrese de que su endpoint de API responda en 1–2 segundos; las APIs lentas hacen que la búsqueda se sienta poco responsiva.
- Use
%__input__%en elpost_bodypara que la API solo devuelva resultados coincidentes, no el conjunto de datos completo. - Indexe el campo de búsqueda en el servidor (p. ej., Elasticsearch, índice de texto completo de base de datos) para respuestas rápidas.
- Limite los resultados a 20–50 elementos por consulta; devolver miles de resultados anula el propósito de la búsqueda.
- Incluya un requisito de longitud mínima de entrada en la API para evitar activar consultas amplias con entradas de un solo carácter.
Limitaciones
- La búsqueda dinámica requiere conectividad de red; no funciona sin conexión.
- El marcador
%__input__%se inyecta tal cual; sanee las entradas en el servidor para prevenir ataques de inyección. - Las expresiones de visualización
@{func}complejas pueden tener soporte limitado en todas las versiones del cliente rtSurvey.