Importar datos de una API externa

Este artículo describe cómo utilizar la función de Importar para importar datos de una Interfaz de Programación de Aplicaciones (API) externa, y especifica los requisitos de formato de la API.

Para seguir este proceso, necesita tener los siguientes roles y permisos:

• Permiso para Añadir registros al Formulario de destino
• Editar registros si está actualizando Registros existentes
• Añadir Formularios, carpetas e informes (para poder diseñar el Formulario, si necesita un nuevo Formulario)

Formato de datos de origen admitido

• La API debe proporcionar una respuesta en formato JSON
• La respuesta JSON debe contener una matriz de objetos JSON, por ejemplo:

[
  { "name": "North Kivu", "code": "RD001" },
  { "name": "South Kivu", "code": "RD002" },
  { "name": "Ituri", "code": "RD003" }
]

• Se admiten objetos anidados, por lo que el siguiente ejemplo sería correcto:

{ "status": "OK",
  "data": 
    [  
      { "name": "North Kivu", "code": "RD001" },
      { "name": "South Kivu", "code": "RD002" }, 
      { "name": "Ituri", "code": "RD003" }
    ]
}

• Los nombres de los Campos deben ser consistentes, por lo que el siguiente ejemplo no funcionaría:

[
  { "location": "North Kivu" },
  { "loc": "South Kivu" },
  { "Location": "Ituri" }
]

• El punto final de la API debe admitir la solicitud HTTP GET

• Si la API no es pública, se admiten dos tipos de cabeceras Authorization:

• Autenticación de acceso básica: un nombre de usuario y una contraseña en codificación Base64

• Token portador: un único token secreto. ActivityInfo enviará la cabecera de Autorización en el formato “Bearer ” como parte de la solicitud

• Accesible a través de HTTPS

Importar datos de la API

Para importar datos de la API utilizando la función de Importar, siga estos pasos:

1. Compruebe si cumple los prerrequisitos:

• Tener una cuenta de ActivityInfo
• Acceso al Formulario
• Permisos apropiados

2. Cree un Formulario en el que vaya a importar los datos. Es importante definir la estructura del Formulario antes de importar los datos.
   Si ya tiene un Formulario, navegue a la vista de Tabla del mismo.
3. Seleccione la herramienta “Importar” de la Barra de Herramientas.

4. Haga clic en “De la API.”

5. Configure la importación de la API rellenando los siguientes campos:

• URL de la API: pegue el enlace aquí. Solo se admiten protocolos seguros (https).
• Seleccione el método de autenticación, dependiendo del servicio externo: “Ninguna” para una API pública, por ejemplo; “Token portador” o “Autenticación básica”. Consulte la documentación de la API que está utilizando para determinar qué método de autenticación es compatible.

6. Haga clic en “Continuar” y espere a que se carguen los datos.
7. Seleccione la ruta de los datos en la ventana de Vista previa de datos. Si la API no proporciona una matriz de objetos directamente, entonces necesita elegir una ruta a la matriz para importar.
   En este ejemplo, seleccione “data” como la ruta de consulta de la API.

Si tiene múltiples rutas de datos disponibles en la lista desplegable, entonces necesita determinar qué parte de la respuesta quiere importar.
En este ejemplo, puede ver que hay dos matrices de objetos (“provinces” y “changes”) en la respuesta de la API:

{
  "status": "OK",
  "provinces": [
    {
      "name": "North Kivu",
      "code": "RD001"
    },
    {
      "name": "South Kivu",
      "code": "RD002"
    }
  ],
  "changes": [
    { 
      "date": "2025-01-01",
      "version": 1
    },
    {
      "date": "2025-03-02",
      "version": 2
    }
  ]
}

No puede importar ambas matrices al mismo tiempo, necesita elegir una ruta de datos de la lista desplegable.

7. Haga clic en “Continuar” y espere a que se carguen los Registros.

8. Es hora de hacer coincidir las columnas y validar los Campos, haciendo clic en cada columna resaltada para resolver los problemas. Para más información, vea Solución de problemas relacionados con el importador.
   En este paso, puede usar filtros para limitar los datos que quiere importar.

El filtrado no está disponible en los valores de los Campos de referencia múltiple ni en los Campos no asignados. No se admite la asignación de Campos de destino.

Consejo: Puede configurar un Campo escondido con un valor predeterminado en su Formulario para permitir el filtrado en el Campo de origen no asignado. De esta manera, el Campo no asignado se convierte en un Campo asignado.

9. Después de resolver las inconsistencias, haga clic en “Continuar” en la esquina superior derecha.
10. Los usuarios con el permiso “Administrar configuraciones de importación” pueden elegir guardar esta configuración de importación para importaciones de datos repetidas, y compartirla con otros usuarios de la Base de datos. Las configuraciones guardadas no se ejecutan automáticamente.

La opción de configuración guardada incluye los siguientes aspectos:

• Origen de la importación (“De la API” en este caso)
• URL de la API, autorización, ruta de datos
• Coincidencia de Campos, incluyendo valores constantes
• Filtros, si se aplican
• Las credenciales se almacenan, si utiliza la autenticación en el paso. Aunque las credenciales no son visibles para otros usuarios, tenga en cuenta que cualquiera con el permiso para administrar la configuración de importación podrá utilizar las credenciales almacenadas para volver a ejecutar la importación en el futuro.

11. Revise el resumen de “Resumen de importación”:

• Si todo es correcto, proceda al siguiente paso.
• Si necesita empezar de nuevo, haga clic en “Cancelar”.
• Para volver a la parte del proceso de coincidencia de columnas y validación de Campos, haga clic en “Atrás”.
• Active el interruptor “Guardar configuración” para guardar esta configuración de importación, y haga clic en “Continuar” en la ventana emergente.

12. En caso de que esté guardando la configuración, escriba una etiqueta para la configuración guardada, luego haga clic en “Guardar e Importar registros” en la esquina superior derecha.

13. Si no está guardando una configuración personalizada, haga clic en “Importar registros” en la esquina superior derecha y espere a que se carguen las actualizaciones.