Aller au contenu principal

Imports de Masse V4

Imports de masse de profils et de tables personnalisées V4​

Les imports de masse sont utilisés pour envoyer un fichier .csv afin de mettre à jour vos tables de profils ou tables personnalisées en masse. Ils consistent en un corps multipart/form-data contenant 2 fichiers : un fichier CSV (zippé) avec les données, et un fichier JSON avec la définition de l'import.

Ils sont réalisés avec les opérations suivantes pour 'Create a profile table import' et 'Create a custom table import':

POST /v4/entity/{entity}/table/{table}/import pour les tables de profils

POST /v4/entity/{entity}/customTable/{table}/import pour les tables personnalisées

Quel est l'équivalent V5 ?​

Il y a deux équivalents V5 pour importer des données en masse :

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

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

Quels sont leurs avantages ?​

En plus du même périmètre fonctionnel que les imports V4, les 2 opérations V5 d'ETL bénéficient de toutes les fonctionnalités supplémentaires inhérentes aux ETL, à savoir :

  • Transformation de données : des transformations peuvent être appliquées pour formater les données avant de les charger dans vos tables Actito.

  • Récupération du fichier sur un emplacement cloud : au lieu de pousser le fichier directement dans le corps de l'appel, les ETL one shot peuvent récupérer le fichier directement sur un emplacement cloud, comme un serveur FTP.

astuce

Récupérer le fichier à distance est une possibilité et non une obligation.
Le fichier peut toujours être fourni directement dans le corps de l’appel API, comme pour les imports V4.

Quelle est la différence entre les 2 alternatives ?​

  • Avec les ETL one shot, la définition des paramètres d'import (tables visées, mapping, transformations, destinataires du rapport,...) est fournie dans l'appel API, en même temps que le fichier de données.
    Il est principalement utilisé pour des imports non récurrents occasionnelles avec des paramètres qui changent à chaque import.

  • Avec les exécutions d'ETL déclenchées par API, les paramètres d'import ont été prédéfinis au préalable et ont une définition fixe, l'appel API ne sert donc qu'à pousser le fichier de données.
    Il est idéal pour les imports récurrents, où vous disposez des mêmes flux de données à une fréquence définie (même table, mapping, etc.).

    Bien sûr, si vous avez des flux de données dans différentes tables, vous pouvez configurer plusieurs définitions ETL, ou même un ETL multifichiers, qui vous permet d'importer des données dans différentes tables dans un ordre séquentiel défini (ce qui n'est pas possible avec les "ETL one shot" ).

    De plus, la définition des "exécutions d'ETL déclenchées par API" est visible dans l'interface utilisateur (alors que seuls les ETL one shot "terminés" sont visibles), permettant aux marketeurs d'avoir une vue d'ensemble de leurs flux de données récurrents.

astuce

Comme il existe généralement une logique et une fréquence pour les imports, nous pensons que les "exécutions d'ETL déclenchées par API" seront la meilleure option dans la plupart des cas.

Comment mettre à jour ces appels ?​

Pour aider les développeurs dans leurs mises à jour, une procédure pas à pas est disponible sur le portail des développeurs.

Il présente les deux options et comment les configurer, avec une comparaison directe des formats entre les opérations v4 et v5.

Quel est le timing ?​

Les imports V4 resteront pris en charge jusqu'à fin juin 2025.

Ils doivent être mis à jour vers des exécutions d'ETL v5 avant cette date.

Suivi des imports​

Une fois un import créé, plusieurs appels peuvent être utilisés pour récupérer le statut, le résultat, le fichier d'erreurs et le fichier de résultat de cet import.

Ces opérations sont remplacées par les opérations V5 équivalentes liées aux ETL one shot. Après avoir créé une exécution ETL one shot, son "id" est donné en réponse, ce qui permet d'effectuer les appels suivants.

Récupérer le statut de l'import​

L'appel V4 pour récupérer le statut de l'import est :

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

Une fois qu'une exécution ETL unique a été créée, son statut peut être récupéré avec l'opération V5 pour 'Get a single ETL execution':

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

La réponse est un peu différente de la V4 car elle inclut une répétition de la définition de l'ETL. L'information du paramètre "status" est l'équivalent de l'appel V4.

Récupérer le résultat de l'import​

Une fois que le statut d'un import était FINISHED, son résultat pouvait être récupéré avec l'appel suivant :

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

Vous pouvez désormais récupérer le résultat d'une exécution one shot avec l'opération V5 pour 'Get a single ETL execution's results':

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

astuce

Il est également possible (et recommandé !) de mettre en place un webhook sur les exécutions ETL.

Récupérer les fichiers d'erreur et de résultat​

En fonction du résultat de l'import, vous pouviez

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

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

Avec les exécutions ETL one shot, vous pouvez désormais récupérer les deux fichiers en même temps, grâce à l'opération V5 pour 'Get a single ETL execution's output files' :

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

astuce

Pour pouvoir récupérer les fichiers de sortie, leur génération doit être définie dans les paramètres de l'ETL one shot.