Saltar al contenido principal

Importaciones de Masas V4

Importaciones masivas de perfiles y tablas personalizadas V4​

Las importaciones masivas se utilizan para enviar un archivo .csv para actualizar sus tablas de perfil o tablas personalizadas de forma masiva. Consisten en un cuerpo multipart/form-data que contiene 2 archivos: un archivo CSV (comprimido) con los datos y un archivo JSON con la definición de importación.

Se llevan a cabo con las siguientes operaciones para 'Crear una importación de tabla de perfil' y 'Crear una importación de tabla personalizada':

POST /v4/entity/{entity}/table/{table}/import para tablas de perfil

POST /v4/entity/{entity}/customTable/{table}/import para tablas personalizadas

¿Cuál es el equivalente V5?​

Hay dos equivalentes V5 para la importación masiva de datos:

POST /mass-imports/v5/entities/{entity}/etl-executions

POST /mass-imports/v5/entities/{entity}/etls/{etlId}/trigger-execution

Cuáles son las ventajas ?​

Además del mismo alcance funcional que las importaciones V4, las 2 operaciones ETL V5 se benefician de todas las funcionalidades adicionales inherentes a ETL, a saber:

  • Transformación de datos: transformaciones se pueden aplicar para formatear los datos antes de cargarlos en tus tablas Actito.

  • Recuperar el archivo en una ubicación en la nube: en lugar de enviar el archivo directamente al cuerpo de la llamada, los ETL de una sola vez pueden recuperar el archivo directamente en una ubicación en la nube, como un servidor FTP.

consejo

Recuperar el archivo de forma remota es una posibilidad y no una obligación.
El archivo aún se puede proporcionar directamente en el cuerpo de la llamada API, como ocurre con las importaciones V4.

¿Cuál es la diferencia entre las 2 alternativas?​

  • Con ETL de una sola vez, la definición de los parámetros de importación (tablas de destino, mapeo, transformaciones, destinatarios de informes, etc.) se proporciona en la llamada API, al mismo tiempo que el archivo de datos.
    Se utiliza principalmente para importaciones ocasionales no recurrentes con parámetros que cambian en cada importación.

  • Con ejecuciones ETL activadas por API, los parámetros de importación se han predefinido de antemano y tienen una definición fija, por lo que la llamada a la API solo sirve para enviar el archivo de datos.
    Es ideal para importaciones recurrentes, donde tienes los mismos flujos de datos con una frecuencia definida (misma tabla, mapeo, etc.).

    Por supuesto, si tiene flujos de datos en diferentes tablas, puede configurar múltiples definiciones ETL, o incluso ETL de múltiples archivos, lo que le permite importar datos en diferentes tablas en un orden secuencial definido (lo cual no es posible con "ETL de una sola vez"). ".

    Además, la definición de "ejecuciones de ETL activadas por API" es visible en la interfaz de usuario (mientras que solo son visibles los ETL de un solo uso "completados"), lo que permite a los especialistas en marketing tener una descripción general de sus flujos de datos recurrentes.

consejo

Como suele haber una lógica y una frecuencia para las importaciones, creemos que las "ejecuciones ETL activadas por API" serán la mejor opción en la mayoría de los casos.

¿Cómo actualizo estas llamadas?​

Para ayudar a los desarrolladores con sus actualizaciones, se ofrece un tutorial está disponible en el Portal del desarrollador.

Analiza ambas opciones y cómo configurarlas, con una comparación directa de formato entre las operaciones v4 y v5.

¿Cuál es el momento?​

Las importaciones de V4 seguirán siendo compatibles hasta finales de junio de 2025.

Deben actualizarse a ejecuciones ETL v5 antes de esta fecha.

Seguimiento de importaciones​

Una vez que se ha creado una importación, se pueden utilizar varias llamadas para recuperar el estado, el resultado, el archivo de errores y el archivo de resultados de esta importación.

Estas operaciones se reemplazan por las operaciones V5 equivalentes vinculadas a ETL de un solo uso. Después de crear una ejecución ETL única, se proporciona su "id" en respuesta, lo que permite realizar llamadas posteriores.

Recuperar estado de importación​

La llamada V4 para recuperar el estado de la importación es:

GET /v4/entity/{entity}/import/{import}/status

Una vez que se ha creado una ejecución ETL única, su estado se puede recuperar con la operación V5 para 'Obtener una ejecución ETL única':

GET /mass-imports/v5/entities/{entity}/etl-executions/{etlExecutionId}

La respuesta es un poco diferente a la de V4 porque incluye una repetición de la definición de ETL. La información del parámetro "estado" es el equivalente a la llamada V4.

Obtener el resultado de la importación​

Una vez que el estado de una importación fuera FINISHED, su resultado podría recuperarse con la siguiente llamada:

GET /v4/entity/{entity}/import/{import}/result

Ahora puede recuperar el resultado de una ejecución única con la operación V5 para 'Obtener los resultados de una única ejecución ETL':

GET /mass-imports/v5/entities/{entity}/etl-executions/{executionId}/integration-results

consejo

También es posible (¡y recomendado!) configurar un webhook sobre ejecuciones ETL.

Recuperar archivos de errores y resultados​

Dependiendo del resultado de la importación, podrías

GET /v4/entity/{entity}/import/{import}/errors

GET /v4/entity/{entity}/import/{import}/result-file

Con las ejecuciones ETL de una sola vez, ahora puede recuperar ambos archivos al mismo tiempo, gracias a la operación V5 para 'Obtener los archivos de salida de una única ejecución ETL':

GET /mass-imports/v5/entities/{entity}/etl-executions/{executionId}/output-files

truco

Para poder recuperar los archivos de salida, su generación debe estar definida en los parámetros del one shot ETL.