Automatiser l'exécution d'une préparation à l'aide d'API

En plus de la fonctionnalité Run (Exécuter) de l'application Talend Cloud Data Preparation, il est possible d'exécuter des préparations à l'aide d'appels d'API, avec peu de configuration, voire aucune.

Cette option signifie que vous pouvez également utiliser Qlik Application Automation ou un outils tiers pour planifier et automatiser vos exécutions de préparations.

Cet exemple utilise une préparation existante nommée customers_preparation, basée sur un jeu de données contenant des données client·es stockées dans une base de données. La préparation applique des opérations de formatage aux données et est exécutée sur un nouveau jeu de données. Vous allez à présent utiliser des appels d'API pour exécuter à nouveau cette préparation et nettoyer régulièrement les données entrantes. La documentation suivante décrit les quatre principales étapes d'exécution d'une préparation : Lister les préparations, démarrer des exécutions, monitorer les exécutions et récupérer l'historique.

Conseil : L'API d'exécution sélectionne automatiquement la configuration d'exécution correspondant à la dernière exécution réussie déclenchée manuellement par un·e utilisateur·trice depuis l'interface de Talend Cloud Data Preparation, ce qui peut causer des problèmes lors d'exécutions automatiques d'API. Lorsque votre préparation est prête pour exécution via l'API, il est recommandé de la dupliquer dans un dossier dédié. Ainsi, les exécutions manuelles n'interfèrent pas avec la préparation.

Si vous souhaitez consulter la documentation des endpoints d'API utilisés dans ce scénario, ouvrez la page de la documentation Swagger correspondant à votre environnement et sélectionnez Talend Data Preparation - Run API. Pour plus d'informations, consultez Accéder à la documentation de l'API REST de Talend Data Preparation.

Avant de commencer

Pour exécuter une préparation via une API, les conditions suivantes doivent être respectées :

Vous avez accès à la préparation en tant que propriétaire ou via un partage.
Vous avez démarré manuellement la préparation dans l'interface de Talend Cloud Data Preparation au moins une fois.
La destination de la préparation n'est pas le téléchargement direct (Direct download).
Vous avez accès au jeu de données de destination en tant que propriétaire ou via un partage.
L'exécution manuelle de la préparation s'est bien terminée.

Récupérer l'ID de la préparation

La première étape d'utilisation d'un endpoint consiste à lister les préparations compatibles et à récupérer l'id de la préparation à exécuter. Le nom de l'endpoint utilisé pour cette étape est List preparation.

Procédure

À l'aide de la méthode GET, saisissez l'endpoint suivant :
```
https://<tdp_environment>/transform/preparations/automation/preparations
```
Dans cet exemple et les suivants, <tdp_environment> correspond à l'URL de votre instance de Talend Cloud Data Preparation. Pour plus d'informations concernant l'URL à utiliser en fonction de votre centre de données, consultez URL vers les applications Talend Cloud.
Envoyez la requête.
L'en-tête de réponse se présente comme suit :
```
[
  {
    "id": "74604d94-c013-4a58-b3c6-00b0075a35f4",
    "name": "customers_preparation",
    "folder": "preparations"
  }
]
```
Le caractère / dans le champ du dossier (folder) signifie que la préparation se situe dans le dossier racine de Talend Cloud Data Preparation. Si elle se situait dans un autre dossier, l'en-tête se présenterait comme suit : /<folder_1>/<subfolder_1>.

Résultats

Copiez l'id de la préparation récupérée, 74604d94-c013-4a58-b3c6-00b0075a35f4 dans cet exemple. Vous aurez besoin de cet ID pour lancer la préparation dans l'étape suivante. Il est également possible de récupérer l'ID de la préparation à partir de l'URL de votre préparation ouverte dans Talend Cloud Data Preparation.

Exécuter la préparation

À l'aide de l'id précédemment récupéré de la préparation, vous allez appeler l'endpoint utilisé pour exécuter la préparation. Le nom de l'endpoint utilisé pour cette étape est Run preparation.

Procédure

À l'aide de la méthode POST, saisissez l'endpoint suivant :

https://<tdp_environment>/transform/preparations/automation/preparations/<preparation_id>/runs

Envoyez la requête.
L'en-tête de réponse se présente comme suit :
```
{
  "id": "848df626-1389-40b9-a7ba-5719faf12e86"
}
```

Résultats

L'exécution de la préparation a démarré et l'id récupéré dans ce cas est un ID d'exécution (run id) et non un ID de préparation (preparation id). Copiez la valeur d'id, 848df626-1389-40b9-a7ba-5719faf12e86 dans cet exemple, dont vous aurez besoin pour l'endpoint de monitoring.

Monitorer l'exécution de la préparation

Une fois l'exécution démarrée, vous pouvez utiliser un endpoint différent pour monitorer son statut à l'aide de l'ID d'exécution récupéré lors de l'étape précédente. Le nom de l'endpoint utilisé pour cette étape est Get Run.

Procédure

À l'aide de la méthode GET, saisissez l'endpoint suivant :

https://<tdp_environment>/transform/preparations/automation/runs/<run_id>

Envoyez la requête.
L'en-tête de réponse se présente comme suit :
```
{
  "id": "848df626-1389-40b9-a7ba-5719faf12e86",
  "preparationId": "74604d94-c013-4a58-b3c6-00b0075a35f4",
  "status": "FINISHED",
  "start": "2024-07-25T21:03:49.919Z",
  "duration": "PT41.278S"
}
```
Les statuts possibles de votre exécution sont les suivants :
- QUEUEING (dans la file d'attente)
- RUNNING (en cours d'exécution)
- FINISHED (terminée)
- ERROR (erreur)
- NO_MORE_AVAILABLE_EXECUTOR (aucun exécuteur disponible)
- SEMANTIC_TYPES_UNAVAILABLE (types sémantiques indisponibles)

Résultats

L'en-tête de la réponse indique dans le champ status (statut) que l'exécution de la préparation est terminée. Si une erreur est survenue au cours de l'exécution, la réponse comprendra également un log complet pour vous permettre d'identifier la cause de l'erreur.

Obtenir l'historique des exécutions

La préparation a été lancée au moins une fois à l'aide de l'API, ce qui signifie que vous pouvez à présent consulter l'historique d'exécution de cette préparation spécifique, à l'aide de l'ID de la préparation. Le nom de l'endpoint utilisé pour cette étape est Get run history.

Procédure

À l'aide de la méthode GET, saisissez l'endpoint suivant :

https://<tdp_environment>/transform/preparations/automation/preparations/<preparation_id>/runs

Envoyez la requête.

L'en-tête de réponse se présente comme suit :

[
  {
    "id": "848df626-1389-40b9-a7ba-5719faf12e86",
    "preparationId": "74604d94-c013-4a58-b3c6-00b0075a35f4",
    "status": "FINISHED",
    "start": "2024-07-25T21:03:49.919Z",
    "duration": "PT41.278S"
  }
]

Résultats

Vous pouvez voir le résumé et le statut des dernières exécutions. La réponse n'affiche qu'une exécution dans cet exemple, mais en inclura d'autres lorsque vous aurez exécuté la préparation plusieurs fois.

L'historique récupéré dans la réponse n'affiche que les exécutions lancées à l'aide de l'API. À l'inverse, l'historique d'exécution Run history de l'interface de Talend Cloud Data Preparation n'affiche que les exécutions lancées manuellement dans l'application.

Cette page vous a-t-elle aidé ?

Si vous rencontrez des problèmes sur cette page ou dans son contenu – une faute de frappe, une étape manquante ou une erreur technique – faites-le-nous savoir.

Laissez vos commentaires ici