Développer des pipelines déclaratifs Spark Lakeflow avec des bundles de ressources Databricks

Les bundles de ressources Databricks, également appelés bundles, vous permettent de valider, déployer et exécuter des ressources Azure Databricks telles que des pipelines déclaratifs Spark Lakeflow. Voir Qu’est-ce que les offres groupées de ressources Databricks ?.

Cette page explique comment créer un bundle pour gérer par programme un pipeline. Consultez pipelines déclaratifs Lakeflow Spark. Le bundle est créé à l’aide de la commande Databricks CLI pipelines init, qui définit un pipeline ETL et un job pour l’exécuter. Vous validez, déployez et exécutez le pipeline déployé dans votre espace de travail Azure Databricks sur le calcul sans serveur.

Conseil

Si vous avez des pipelines existants créés à l’aide de l’interface utilisateur Azure Databricks ou de l’API 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 à l’aide des étapes ci-dessous, puis d’ajouter la configuration et d’autres sources au bundle. Consultez Récupérer une définition de pipeline existante à l’aide de l’interface utilisateur.

Spécifications

• Databricks CLI version 0.283.0 ou ultérieure. Pour vérifier la version installée de l’interface CLI Databricks, exécutez la commande databricks -v. Pour installer l’interface CLI Databricks, consultez Installer ou mettre à jour l’interface CLI Databricks.
• uv est nécessaire pour exécuter des tests et installer des dépendances pour ce projet à partir d’un IDE.
• L’espace de travail distant doit avoir les fichiers d’espace de travail activés. Voir Qu’est-ce que les fichiers d’espace de travail ?.
• Catalogue déjà existant pour les tables du pipeline. Consultez Créer des catalogues.

(Facultatif) Installer un module Python pour prendre en charge le développement local de pipelines

Databricks fournit un module Python pour faciliter le développement local du code des pipelines déclaratifs Spark Lakeflow en offrant la vérification de la syntaxe, la saisie semi-automatique et la vérification du type de données pendant que vous écrivez du code dans votre IDE.

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

Étape 1 : Configurer l’authentification

Tout d’abord, configurez l’authentification entre l’interface CLI Databricks sur votre ordinateur de développement et votre espace de travail Azure Databricks. Cette page part du principe que vous souhaitez utiliser l’authentification utilisateur à machine OAuth (U2M) et un profil de configuration Azure Databricks correspondant nommé DEFAULT pour l’authentification.

Note

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

1. Utilisez l’interface CLI Databricks pour lancer la gestion des jetons OAuth localement en exécutant la commande suivante pour chaque espace de travail cible.

   Dans la commande suivante, remplacez <workspace-url> par votre URL Azure Databricks par espace de travail, par exemple https://adb-1234567890123456.7.azuredatabricks.net.

   databricks auth login --host <workspace-url>
   

2. L’interface CLI Databricks vous invite à enregistrer les informations que vous avez entrées en tant que profil de configuration Azure Databricks. Appuyez sur Enter pour accepter le nom de profil suggéré, ou saisissez le nom d’un nouveau profil ou d’un profil existant. Tout profil existant portant le même nom sera écrasé par les informations que vous avez saisies. Vous pouvez utiliser les profils pour changer rapidement de contexte d’authentification entre plusieurs espaces de travail.

   Pour obtenir la liste des profils existants, dans un autre terminal ou une autre invite de commandes, utilisez l’interface CLI Databricks pour exécuter la commande databricks auth profiles. Pour afficher 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 espace de travail Azure Databricks.

4. Pour afficher la valeur actuelle du jeton OAuth d’un profil et l’horodatage d’expiration à venir du jeton, 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 disposez de plusieurs profils avec la même valeur --host, vous devrez peut-être spécifier conjointement les options --host et -p pour aider Databricks CLI à retrouver les bonnes informations de token OAuth.

Étape 2 : Créer le bundle

Initialisez un bundle en utilisant un pipeline:

1. Utilisez votre terminal ou invite de commandes pour basculer vers un répertoire sur votre ordinateur de développement local qui contiendra le bundle généré du modèle.

2. Utilisez l’interface CLI Databricks pour exécuter la commande pipelines init :

   databricks pipelines init
   

3. Pour Unique name for this project, conservez la valeur par défaut de my_pipeline_project ou saisissez une valeur différente, puis appuyez sur Enter. Cela 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 consulter les fichiers générés par le modèle, basculez vers le répertoire racine du bundle que vous venez de créer. La structure suivante est créée par défaut :

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 particulièrement importants 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 des variables de catalogue et de schéma et spécifie les paramètres des espaces de travail cibles.

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

• src/: ce dossier contient les fichiers sources, les explorations et les transformations de l’exemple de pipeline.

  Conseil

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

  uv run pytest
  

• README.md: ce fichier contient des informations supplémentaires sur la prise en main et l’utilisation de ce modèle groupé.

Étape 4 : Valider la configuration de l’offre groupée

Vérifiez maintenant si la configuration de l’offre groupée est valide.

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

   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 sur l’espace de travail distant

Ensuite, déployez l’offre groupée sur votre espace de travail Azure Databricks distant et vérifiez le pipeline dans votre espace de travail.

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

   databricks bundle deploy --target dev
   

   Ou:

   databricks pipelines deploy --target dev
   

   Note

   Le modèle par défaut inclut un travail qui exécute le pipeline tous les jours, mais celui-ci est mis en pause dans le mode de déploiement cible dev. Consultez les modes de déploiement de Databricks Asset Bundle .

2. Vérifiez que le paquet a été déployé :

   1. Dans la barre latérale de votre espace de travail Azure Databricks, cliquez sur Espace de travail.
   2. Cliquez dans le dossier Utilisateurs ><your-username>>.bundle et recherchez votre projet groupé.

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

   1. Dans la barre latérale de votre espace de travail Azure Databricks, cliquez sur Travaux & Pipelines.
   2. Vous pouvez, si vous le souhaitez, sélectionner les filtres Pipelines et Qui m'appartiennent.
   3. Cliquez sur [dev <your-username>] <project-name>_etl.

Si vous modifiez votre bundle après cette étape, vous devez répéter les étapes 4 à 5 pour vérifier que la configuration du bundle est toujours valide, puis redéployer le projet.

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

À présent, déclenchez une exécution du pipeline dans votre espace de travail à partir de la ligne de commande.

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

   databricks pipelines run my_pipeline_project_etl --target dev
   

2. Copiez la valeur de Update URL qui s’affiche dans votre terminal et collez cette valeur dans votre navigateur pour ouvrir votre espace de travail Azure Databricks.

3. Dans votre espace de travail Azure Databricks, une fois l’exécution du pipeline terminée, cliquez sur les vues matérialisées pour afficher les détails de chaque vue.

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

Étape 7 : Historique des sorties et journaux des événements

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

Pour récupérer les exécutions précédentes du pipeline :

databricks pipelines history my_pipeline_project_etl

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 générer (en JSON) les événements de la dernière mise à jour du pipeline :

databricks pipelines logs my_pipeline_project_etl

Permet jq de filtrer les résultats. Voir Filtrer la sortie JSON avec jq.

Étape 8 : Nettoyer

Dans cette étape, vous supprimez le bundle déployé et le pipeline de votre espace de travail.

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

   databricks pipelines destroy --target dev
   

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

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