Développez un Job avec des Declarative Automation Bundles

Les Declarative Automation Bundles (anciennement appelés Databricks Asset Bundles) contiennent les artefacts que vous souhaitez déployer et les paramètres pour les ressources Databricks, tels que les Jobs que vous souhaitez exécuter, et vous permettent de les valider, de les déployer et de les exécuter par programme. Consultez Que sont les Declarative Automation Bundles ?

Cette page explique comment créer un bundle pour gérer un Job par programme. See Lakeflow Jobs. Le bundle est créé à l'aide du template de bundle par défaut des Declarative Automation Bundles pour Python, qui se compose d'un notebook et de la définition d'un job pour l'exécuter. Vous validez, déployez et exécutez ensuite le Job déployé dans votre Workspace Databricks.

astuce

Si vous avez des jobs existants qui ont été créés à l'aide de l'interface utilisateur ou de l'API Lakeflow Jobs 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 de vérifier si le bundle fonctionne. Vous pouvez ensuite ajouter des définitions de job supplémentaires, des notebooks et d'autres sources au bundle. Voir Récupérer la définition d'un job existant à l'aide de l'interface utilisateur.

Si vous souhaitez créer un bundle à partir de zéro, consultez Créer un bundle manuellement.

Exigences

• Databricks CLI version 0.218.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 Databricks distant doit avoir les fichiers de workspace activés. Consultez Qu'est-ce qu'un fichier de workspace ?.
• Un catalogue existant. Pour créer un catalogue, consultez Créer des catalogues.

É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 : initialiser le bundle

Initialisez un bundle à l'aide du template de projet de bundle Python par default.

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 bundle init :

   Bash

   databricks bundle init

3. Pour Template to use, laissez la valeur par défaut de default-python en appuyant sur Enter.

4. Pour Unique name for this project, laissez la valeur default de my_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.

5. Pour Include a job that runs a notebook, sélectionnez yes et appuyez sur Enter.

6. Pour Include an ETL pipeline, sélectionnez no et appuyez sur Enter.

7. Pour Include a stub (sample) Python package, sélectionnez no et appuyez sur Enter.

8. Pour Use serverless, sélectionnez yes et appuyez sur Enter. Ceci indique au CLI Databricks de configurer votre bundle pour qu'il s'exécute sur un compute serverless.

9. Pour Default catalog for any tables created by this project [hive_metastore], entrez le nom d'un catalogue Unity Catalog existant.

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

É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. Les fichiers présentant un intérêt particulier incluent les éléments 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: Ce fichier spécifie les paramètres du Job, y compris une tâche de Notebook default. Pour plus d'informations sur les paramètres de job, consultez Job.
• src/: Ce dossier contient les fichiers source du job.
• src/sample_notebook.ipynb: Ce Notebook lit une table d'exemple.
• tests/: Ce dossier contient des exemples de tests unitaires.
• README.md : ce fichier contient des informations supplémentaires sur la prise en main et l'utilisation de ce Template de bundle.

astuce

Vous pouvez définir, combiner et remplacer les paramètres des nouveaux clusters de job dans les bundles en utilisant les techniques décrites dans Remplacer avec les paramètres cibles.

É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 bundle vers le workspace distant

Ensuite, déployez le Job sur votre Workspace Databricks distant et vérifiez le Job au sein de votre Workspace.

1. Depuis la racine du bundle, utilisez la CLI Databricks pour exécuter la commande bundle deploy :

   Bash

   databricks bundle deploy --target dev

2. Confirmez que le notebook a bien été déployé :

   1. Dans la barre latérale de votre Workspace Databricks, cliquez sur Workspace .
   2. Cliquez dans le dossier Users > <your-username> > .bundle > <project-name> > dev > files > src . Le Notebook doit se trouver dans ce dossier.

3. Vérifiez si le job a été créé :

   1. Dans la barre latérale de votre workspace Databricks, cliquez sur Tâches & Pipelines .
   2. Facultativement, sélectionnez les filtres **Jobs** et **Appartenant à moi**.
   3. Cliquez sur [dev <your-username>] sample_job .
   4. Cliquez sur l'onglet **tab**. Il doit y avoir une **notebook_task**.

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écutez le job déployé

Trigger maintenant l'exécution du Job dans votre Workspace à partir de la ligne de commande.

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

   Bash

   databricks bundle run --target dev sample_job

2. Copiez la valeur de Run URL qui apparaît dans votre terminal et collez cette valeur dans votre navigateur web pour ouvrir votre workspace Databricks. Consultez Afficher et exécuter un Job créé avec les Declarative Automation Bundles

3. Dans votre Workspace Databricks, une fois la tâche Job terminée avec succès et qu'une barre de titre verte s'affiche, cliquez sur la tâche Job pour voir les résultats.

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 : Exécuter les tests

Enfin, utilisez pytest pour exécuter les tests localement :

uv run pytest

Étape 8 : Nettoyage

Dans cette étape, vous supprimez le notebook déployé et le job de votre workspace.

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

   Bash

   databricks bundle destroy --target dev

2. Lorsque vous êtes invité à supprimer définitivement tous les fichiers et répertoires du Workspace, 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.