Aller au contenu principal
Dernière mise à jour le

Développez des pipelines avec Declarative Automation Bundles

Les bundles d'automatisation déclarative (anciennement appelés Databricks Asset Bundles) vous permettent de valider, déployer et exécuter par programme des ressources Databricks telles que les LakeFlow Pipelines. Consultez Que sont les Declarative Automation Bundles ?

Cette page décrit comment créer un bundle pour gérer un pipeline par programmation. See Spark Declarative Pipelines. Le bundle est créé à l’aide de la commandepipelines init Databricks CLI, qui définit un pipeline ETL et un Job pour l’exécuter. Vous validez, déployez et exécutez ensuite le pipeline déployé dans votre workspace Databricks sur compute serverless.

astuce

Si vous avez des pipelines existants qui ont été créés à l'aide de l'interface utilisateur ou de l'API Databricks et que vous souhaitez déplacer vers des bundles, vous devez les définir dans les fichiers de configuration d'un bundle. Databricks vous recommande de créer d'abord un bundle en suivant les étapes ci-dessous, puis d'y ajouter la configuration et d'autres sources. Voir Récupérer une définition de pipeline existante à l'aide de l'interface utilisateur.

Exigences​

  • Databricks CLI version 0,283,0 ou supérieure. Pour vérifier la version installée de la Databricks CLI, exécutez la commande databricks -v. Pour installer la Databricks CLI, consultez Installer ou mettre à jour la Databricks CLI.
  • uv est nécessaire pour exécuter les tests et installer les dépendances de ce projet depuis un IDE.
  • Le workspace distant doit avoir les fichiers de workspace activés. Consultez Qu'est-ce qu'un fichier de workspace ?.
  • Un catalogue existant pour les tables dans le pipeline. Consultez Créer des catalogues.

(Facultatif) Installez un module Python pour prendre en charge le développement de pipelines locaux.​

Databricks fournit un module Python pour faciliter le développement local de votre code LakeFlow Pipelines en offrant la vérification de la syntaxe, la saisie semi-automatique et la vérification des types de données lorsque vous écrivez du code dans votre IDE.

Le module Python pour le développement local est disponible sur PyPi. Pour installer le module, consultez Python stub pour DLT.

Étape 1 : Configurez l'authentification​

Tout d'abord, configurez l'authentification entre le Databricks CLI sur votre machine de développement et votre Databricks Workspace. Cette page suppose que vous souhaitez utiliser l'authentification OAuth d'utilisateur à machine (U2M) et un profil de configuration Databricks correspondant nommé DEFAULT pour l'authentification.

remarque

L'authentification U2M est appropriée pour essayer ces étapes en temps réel. Pour les workflows entièrement automatisés, Databricks recommande d'utiliser l'authentification OAuth machine à machine (M2M) à la place. Consultez les instructions de configuration de l'authentification M2M dans Autoriser l'accès du service principal à Databricks avec OAuth.

  1. Utilisez la CLI Databricks pour initier la gestion locale des jetons OAuth en exécutant la commande suivante pour chaque workspace cible.

    Dans la commande suivante, remplacez <workspace-url> par l'URL de votre instance de workspace Databricks, par https://dbc-a1b2345c-d6e7.cloud.databricks.com exemple.

    Bash
    databricks auth login --host <workspace-url>

  2. La CLI Databricks vous invite à enregistrer les informations que vous avez saisies en tant que profil de configuration Databricks. Appuyez sur Enter pour accepter le nom de profil suggéré, ou entrez le nom d’un profil nouveau ou existant. Tout profil existant portant le même nom est écrasé avec les informations que vous avez saisies. Vous pouvez utiliser des profils pour basculer rapidement votre contexte d'authentification entre plusieurs Workspaces.

    Pour obtenir une liste de tous les profils existants, dans un terminal ou une invite de commande distinct, utilisez la CLI Databricks pour exécuter la commande databricks auth profiles. Pour consulter les paramètres existants d’un profil spécifique, exécutez la commande databricks auth env --profile <profile-name>.

  3. Dans votre navigateur web, suivez les instructions à l'écran pour vous connecter à votre Databricks Workspace.

  4. Pour afficher la valeur actuelle du token OAuth d'un profil et le timestamp d'expiration à venir du token, exécutez l'une des commandes suivantes :

    • databricks auth token --host <workspace-url>
    • databricks auth token -p <profile-name>
    • databricks auth token --host <workspace-url> -p <profile-name>

    Si vous avez plusieurs profils avec la même valeur --host, vous devrez peut-être spécifier les options --host et -p ensemble pour aider le CLI Databricks à trouver les informations de jeton OAuth correspondantes correctes.

Étape 2 : Créer le bundle​

Initialisez un bundle avec un pipeline :

  1. Utilisez votre terminal ou l’invite de commande pour passer à un répertoire de votre machine de développement locale qui contiendra le bundle généré par le Template.

  2. Utilisez le CLI Databricks pour exécuter la commande pipelines init :

    Bash
    databricks pipelines init

  3. Pour Unique name for this project, laissez la valeur default de my_pipeline_project, ou saisissez une valeur différente, puis appuyez sur Enter. Ceci détermine le nom du répertoire racine de ce bundle. Ce répertoire racine est créé dans votre répertoire de travail actuel.

  4. Pour Initial catalog, entrez le nom d'un catalogue Unity Catalog existant.

  5. Pour Use a personal schema for each user working on this project?, sélectionnez yes.

  6. Pour Initial language for this project, sélectionnez python.

Étape 3 : Explorer le bundle​

Pour afficher les fichiers générés par le template, accédez au répertoire racine de votre nouveau bundle. La structure suivante est créée par default :

my_pipeline_project
├── databricks.yml
├── pyproject.toml
├── README.md
├── resources
│   ├── my_pipeline_project_etl.pipeline.yml
│   └── sample_job.job.yml
└── src
    └── my_pipeline_project_etl
        ├── explorations
        │   └── sample_exploration.ipynb
        ├── README.md
        └── transformations
            ├── sample_trips_my_pipeline_project.py
            └── sample_zones_my_pipeline_project.py

Les fichiers présentant un intérêt particulier sont les suivants :

  • databricks.yml: ce fichier spécifie le nom programmatique du bundle, inclut des références aux fichiers du bundle, définit les variables de catalogue et de schéma, et spécifie les paramètres pour les Workspace cibles.

  • resources/sample_job.job.yml et resources/<project-name>_etl_pipeline.yml: Ces fichiers définissent le Job qui contient une tâche de refresh de pipeline, et les paramètres du pipeline. Pour plus d'informations sur les paramètres de pipeline, consultez le pipeline.

  • src/: Ce dossier contient les fichiers source, les explorations et les transformations de l'exemple de pipeline.

astuce

Si vous ajoutez des tests, utilisez pytest pour les exécuter localement :

Bash
uv run pytest
  • README.md : ce fichier contient des informations supplémentaires sur la prise en main et l'utilisation de ce Template de bundle.

Étape 4 : Validez la configuration du bundle​

Vérifiez maintenant si la configuration du bundle est valide.

  1. À partir du répertoire racine, utilisez la CLI Databricks pour exécuter la commande bundle validate :

    Bash
    databricks bundle validate

  2. Si un résumé de la configuration du bundle est renvoyé, la validation a réussi. Si des erreurs sont renvoyées, corrigez-les, puis répétez cette étape.

Étape 5 : Déployer le pipeline vers le workspace distant​

Ensuite, déployez le bundle sur votre Databricks Workspace distant et vérifiez le pipeline dans votre Workspace.

  1. À partir de la racine du bundle, utilisez une commande CLI Databricks deploy :

    Bash
    databricks bundle deploy --target dev

    Ou :

    Bash
    databricks pipelines deploy --target dev
remarque

Le Template default inclut un Job qui exécute le pipeline tous les jours, mais celui-ci est mis en pause pour le mode de déploiement cible dev. Consultez les modes de déploiement des Declarative Automation Bundles.

  1. Confirmez que le bundle a été déployé :

    1. Dans la barre latérale de votre Workspace Databricks, cliquez sur Workspace .
    2. Cliquez sur le dossier Utilisateurs > <your-username> > .bundle et trouvez votre projet de bundle.

  2. Vérifiez si votre pipeline a été créé :

    1. Dans la barre latérale de votre workspace Databricks, cliquez sur Tâches & Pipelines .
    2. Facultativement, sélectionnez les filtres Pipelines et Propriété .
    3. Cliquez sur [dev <your-username>] <project-name>_etl .

Si vous apportez des modifications à votre bundle après cette étape, vous devriez répéter les étapes 4 et 5 pour vérifier si la configuration de votre bundle est toujours valide et ensuite redéployer le projet.

Étape 6 : Exécuter le pipeline déployé​

trigger maintenant une exécution du pipeline dans votre Workspace depuis la ligne de commande.

  1. À partir du répertoire racine, utilisez la commande pipelines run de la CLI Databricks. S'il n'y a qu'un seul pipeline dans le projet, vous n'avez pas besoin de spécifier de nom de pipeline.

    Bash
    databricks pipelines run my_pipeline_project_etl --target dev

  2. Copiez la valeur de Update URL qui apparaît dans votre terminal et collez cette valeur dans votre navigateur web pour ouvrir votre workspace Databricks.

  3. Dans votre workspace Databricks, une fois l'exécution du pipeline terminée avec succès, cliquez sur les vues matérialisées pour voir les détails de chaque vue.

Si vous apportez des modifications à votre bundle après cette étape, vous devez répéter les étapes 4-6 pour vérifier si votre configuration de bundle est toujours valide, redéployer le projet et exécuter le projet redéployé.

Étape 7 : Historique de sortie et Logs​

Les informations fournies par les commandes pipelines history et pipelines logs peuvent aider à diagnostiquer les défaillances.

Pour récupérer les exécutions passées du pipeline :

Bash
databricks pipelines history my_pipeline_project_etl
Output
Updates Summary for pipeline my_pipeline_project_etl:
Update ID: a62293ec-8a63-43b7-8629-b218d56dac7c
   State: COMPLETED
   Cause: API_CALL
   Creation Time: 2026-01-29T23:16:14Z
   Full Refresh: false
   Validate Only: false

Pour afficher (au format JSON) les événements de la mise à jour la plus récente du pipeline :

Bash
databricks pipelines logs my_pipeline_project_etl

Utilisez jq pour filtrer les résultats. Consultez Filtrer la sortie JSON avec jq.

Étape 8 : Nettoyage​

Au cours de cette étape, vous supprimez le bundle déployé et le pipeline de votre workspace.

  1. À partir du répertoire racine, utilisez la CLI Databricks pour exécuter la commande pipelines destroy :

    Bash
    databricks pipelines destroy --target dev

  2. Lorsque vous êtes invité à détruire définitivement les ressources, le pipeline, ainsi que les tables et les vues gérées par le pipeline, tapez y et appuyez sur Enter.

  3. Si vous souhaitez également supprimer le bundle de votre machine de développement, vous pouvez maintenant supprimer le répertoire de projet local.

Sur cette page