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 ?
L'équivalent V5 pour importer des données en masse est l'opération V5 d'exécution d'ETL one shot.
POST /mass-imports/v5/entities/{entity}/etl-executions
Quels sont ses avantages ?
En plus du même périmètre fonctionnel que les imports V4, l'opération V5 d'ETL one shot bénéficie 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.
Comment mettre à jour ces appels ?
Tout comme les imports V4, l'opération V5 consiste en un corps multipart/form-data contenant 2 fichiers : un fichier CSV avec les données et un fichier JSON avec la définition de l'ETL.
Le path et la définition du fichier JSON diffèrent légèrement entre les opérations V4 et V5. Pour aider les développeurs dans leurs mises à jour, une procédure pas à pas est disponible sur le portail des développeurs.
Quel est le timing ?
Les imports V4 resteront pris en charge jusqu'à fin juin 2025.
Ils doivent être mis à jour vers des exécutions ETL one shot 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
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.