Développer un projet sur Azure Databricks à l’aide des packs de ressources Databricks

Article
10/14/2024

Les regroupements de ressource Databricks, également connus sous le nom de regroupement, contiennent les artefacts que vous souhaitez déployer et les paramètres des ressources Azure Databricks, telles que les tâches que vous souhaitez exécuter, et vous permettent de les valider, de les déployer et de les exécuter de manière programmatique. Consultez Que sont les packs de ressources Databricks ?.

Cet article explique comment créer un regroupement pour gérer un projet de manière programmatique. Consultez Planifier et orchestrer des flux de travail. Le regroupement est créé à l’aide du modèle par défaut des regroupements de ressources Azure Databricks pour Python, qui se compose d’un code de notebook, associé à la définition d’un projet pour l’exécuter. Validez, déployez et exécutez ensuite le projet déployé dans votre espace de travail Databricks Azure.

Conseil

Si vous avez des travaux existants créés à l’aide de l’interface utilisateur ou de l’API Projets Azure Databricks et que vous souhaitez les déplacer vers des groupes, vous devez les définir dans fichier de configuration de groupe. Databricks vous recommande de créer d’abord un regroupement en suivant les étapes ci-dessous et de vérifier si le regroupement fonctionne. Vous pouvez ensuite ajouter des définitions du travail supplémentaires, des notebooks et d’autres sources au regroupement. Consultez Ajouter une définition de tâche existante à un pack.

Spécifications

Databricks CLI 0.218.0 ou une version ultérieure. Pour vérifier la version de Databricks CLI installée, exécutez la commande databricks -v. Pour installer l’interface CLI Databricks, consultez Installer ou mettre à jour l’interface CLI Databricks.
L’espace de travail Databricks distant doit disposer de fichiers d’espace de travail activés. Consultez l’article Que sont les fichiers d’espace de travail ?.

Créer un regroupement à l’aide d’un modèle de projet

Tout d’abord, créez un regroupement à l’aide du gabarit Python par défaut des regroupements de ressources de Databricks. Pour plus d’informations sur les modèles de regroupemetns, consultez Modèles de projet de regroupement de ressources Databricks.

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

Étape 1 : Configurer l’authentification

Dans cette étape, vous configurez l’authentification entre l’interface CLI Databricks sur votre machine de développement et votre espace de travail Azure Databricks. Cet article suppose que vous voulez utiliser l’authentification utilisateur à machine (U2M) OAuth et un profil de configuration Azure Databricks correspondant nommé DEFAULT pour l’authentification.

Remarque

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 machine à machine (M2M) OAuth. Consultez les instructions de configuration de l’authentification M2M dans Authentification.

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 d’espace de travail Azure Databricks, par exemple https://adb-1234567890123456.7.azuredatabricks.net.
```
databricks auth login --host <workspace-url>
```
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 entrez le nom d’un profil nouveau ou existant. Tout profil existant portant le même nom est remplacé par les informations que vous avez entrées. Vous pouvez utiliser des 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 voir les paramètres existants d’un profil spécifique, exécutez la commande databricks auth env --profile <profile-name>.
Dans votre navigateur web, suivez les instructions à l’écran pour vous connecter à votre espace de travail Azure Databricks.
Pour voir la valeur du jeton OAuth actuel d’un profil et l’horodatage de l’expiration à venir du jeton, exécutez 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 pour --host, il peut être nécessaire de spécifier aussi les options --host et -p pour permettre à l’interface CLI Databricks de trouver les informations du jeton OAuth correspondant.

Étape 2 : Initialiser le regroupement

Initialisez un regroupement en utilisant le gabarit de projet de regroupement Python par défaut.

Utilisez votre terminal ou invite de commandes pour basculer vers un répertoire sur votre ordinateur de développement local qui contiendra le pack généré du modèle.
Utilisez l’interface CLI Databricks pour exécuter la commandebundle init :
```
databricks bundle init
```
Pour Template to use, conservez la valeur par défaut default-python en appuyant surEnter.
Pour Unique name for this project, laissez la valeur par défaut de my_project, ou tapez une valeur différente, puis appuyez surEnter . 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.
Pour Include a stub (sample) notebook, sélectionnez yes et appuyez sur Enter.
Pour Include a stub (sample) DLT pipeline, sélectionnez no et appuyez sur Enter. Cela indique à l’interface CLI Databricks de ne pas définir d’exemple de pipeline Delta Live Tables dans votre pack.
Pour Include a stub (sample) Python package, sélectionnez no et appuyez sur Enter. Cela indique à l’interface CLI Databricks de ne pas ajouter d’exemples de fichiers de paquet wheel Python ni d’instructions de build associées à votre pack.

Étape 3 : Explorer le pack

Pour consulter les fichiers générés par le gabarit, basculez vers le répertoire racine de votre regroupement nouvellement créé. Les fichiers d’intérêt particulier sont les suivants :

databricks.yml : ce fichier spécifie le nom programmatique du pack, inclut une référence à la définition de tâche et spécifie les paramètres relatifs à l’espace de travail cible.
resources/<project-name>_job.yml : ce fichier spécifie les paramètres du travail, y compris une tâche de notebook par défaut.
src/notebook.ipynb : ce fichier est un échantillon de notebook qui, lors de l’exécution, initialise simplement un RDD contenant les nombres 1 à 10.

Pour la personnalisation des tâches, les mappages dans une déclaration de tâche correspondent à la charge utile de la demande, exprimée au format YAML, de l’opération de création de projets telle que documentée dans POST /api/2.1/jobs/create dans la référence de l’API REST.

Conseil

Vous pouvez définir, combiner et remplacer les paramètres des nouveaux clusters de travaux dans des packs à l’aide des techniques décrites dans Remplacer les paramètres de cluster dans les packs de ressources Databricks.

Étape 4 : valider le fichier de configuration du pack du projet

Dans cette étape, vous vérifiez si la configuration du pack est valide.

À partir du répertoire racine, utilisez l’interface CLI Databricks pour exécuter la commandebundle validate, comme suit :
```
databricks bundle validate
```
Si un résumé de la configuration de l’offre groupée est retourné, la validation a réussi. Si des erreurs sont renvoyées, corrigez-les , puis répétez cette étape.

Si vous apportez des modifications à votre pack après cette étape, vous devez répéter cette étape pour vérifier si les paramètres de votre pack sont toujours valides.

Étape 5 : Déployer le projet local sur l’espace de travail distant

Au cours de cette étape, vous allez déployer le notebook local dans votre espace de travail Azure Databricks distant et créer le travail Azure Databricks dans votre espace de travail.

À partir du pack racine, utilisez l'interface CLI Databricks pour exécuter la commande bundle deploy, comme suit :
```
databricks bundle deploy -t dev
```
Vérifiez si le notebook local a été déployés : dans la barre latérale de votre espace de travail Azure Databricks, cliquez sur Espace de travail.
Cliquez sur le dossier Utilisateurs ><your-username>> .bundle ><project-name>> dev > fichiers > src . Le notebook doit se trouver dans ce dossier.
Vérifiez si le travail a été créé : dans la barre latérale de votre espace de travail Azure Databricks, cliquez sur Flux de travail.
Sous l’onglet Travaux, cliquez sur [dev <your-username>] <project-name>_job.
Cliquez sur l'onglet Tâches. Il devrait y avoir un travail : notebook_task.

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

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

À cette étape, vous déclenchez une exécution du projet Azure Databricks dans votre espace de travail à partir de la ligne de commande.

À partir du répertoire racine, utilisez l’interface CLI Databricks pour exécuter la commandebundle run, comme suit, en remplaçant<project-name> par le nom de votre projet à l’étape 2 :
```
databricks bundle run -t dev <project-name>_job
```
Copiez la valeur Run URL qui apparaît dans votre terminal et collez cette valeur dans votre navigateur web pour ouvrir votre espace de travail Azure Databricks. Consulter Consulter et exécuter un projet créé avec un regroupement de ressources Databricks
Dans votre espace de travail Azure Databricks, une fois que la tâche du travail est terminée avec succès et affiche une barre de titre verte, cliquez sur la tâche du travail pour afficher les résultats.

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

Étape 7 : Nettoyer

Au cours de cette étape, vous allez supprimer le notebook déployé et le travail de votre espace de travail.

À partir du répertoire racine, utilisez l’interface CLI Databricks pour exécuter la commande bundle destroy, comme suit :
```
databricks bundle destroy -t dev
```
Confirmez la demande de suppression de travail : lorsque l’option de détruire définitivement des ressources s’affiche, tapez y et appuyez sur Enter.
Confirmez la demande de suppression de notebook : lorsque l’option de détruire définitivement le dossier précédemment déployé et tous ses fichiers s’affiche, tapez y et appuyez sur Enter.
Si vous souhaitez également supprimer le pack de votre ordinateur de développement, vous pouvez maintenant supprimer le répertoire local de l’étape 2.

Ajouter une définition de tâche existante à un pack

Vous pouvez utiliser un projet existant comme base pour définir un projet dans un fichier de configuration du regroupement. Pour obtenir une définition du travail existante, vous pouvez la récupérer manuellement à l’aide de l’IU, ou vous pouvez la générer de manière programmatique à l’aide de l’interface CLI Databricks.

Pour plus d’informations sur la définition du travail dans les regroupements, consultez projet.

Obtenir une définition du travail existante à l’aide de l’IU

Pour obtenir la représentation YAML d’une définition du travail existante à partir de l’IU de l’espace de travail Databricks Azure :

Dans la barre latérale de votre espace de travail Azure Databricks, cliquez sur Catalogue.
Sous l'onglet Tâches, cliquez sur le lien du Nom de votre tâche.
En regard du bouton Exécuter maintenant, cliquez sur le kebab, puis sur Commuter vers le code (YAML).
Ajoutez le fichier YAML que vous avez copié dans le fichier databricks.yml de votre regroupement, ou créez un fichier de configuration pour votre projet dans l’annuaire resources de votre projet regroupé et référencez-le à partir de votre fichier databricks.yml. Consultez (/dev-tools/bundles/settings.md#resources).
Téléchargez et ajoutez tout fichier et notebook Python référencés dans le projet existant à la source du projet de regroupement. En règle générale, les artefacts regroupés se trouvent dans l’annuaire src d’un regroupement.

Conseil

Vous pouvez exporter un notebook existant à partir d’un espace de travail Databricks Azure dans le format .ipynb en cliquant sur File> Export > IPython Notebook à partir de l’interface utilisateur du notebook Azure Databricks.

Après avoir ajouté vos notebooks, fichiers Python et autres artefacts au regroupement, assurez-vous que votre définition du travail les référence correctement. Par exemple, pour un notebook nommé hello.ipynb qui se trouve dans l’annuaire src du regroupement :
```
resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
      - task_key: hello-task
        notebook_task:
          notebook_path: ../src/hello.ipynb
```

Générer une définition du travail existante à l’aide de l’interface CLI Databricks

Pour générer de manière programmatique la configuration d’un regroupement pour un projet existant :

Récupérez l’ID du projet existant à partir du panneau latéral Détails du projet pour le projet dans l’interface utilisateur des projets ou utilisez la commande databricks jobs list de CLI Databricks.
Exécutez la bundle generate job commande CLI Databricks, en définissant l’ID tâche :
```
databricks bundle generate job --existing-job-id 6565621249
```
Cette commande crée un fichier de configuration regroupé pour le projet dans le dossier resources du regroupement et télécharge tous les artéfacts référencés dans le dossier src.

Conseil

Si vous utilisez d’abord bundle deployment bind pour lier une ressource d’un ensemble à une ressource de l’espace de travail, la ressource de l’espace de travail est mise à jour en fonction de la configuration définie dans le pack auquel elle est liée après le prochain bundle deploy. Pour plus d’informations sur bundle deployment bind, consultez Les ressources de liaison de regroupement.

Configurez une tâche qui utilise le calcul serverless

Les exemples suivants présentent des configurations de packs pour créer une tâche qui utilise le calcul serverless.

Pour utiliser le calcul serverless afin d’exécuter une tâche qui inclut des tâches de notebook, omettez la configuration job_clusters à partir du fichier de configuration groupé.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job-serverless:
      name: retrieve-filter-baby-names-job-serverless
      tasks:
        - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./filter-baby-names.py

  targets:
    development:
      workspace:
        host: <workspace-url>

Pour utiliser le calcul serverless pour exécuter un travail qui inclut des tâches Python, incluez la configuration environments.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: serverless-python-tasks

resources:
jobs:
  serverless-python-job:
    name: serverless-job-with-python-tasks

    tasks:
      - task_key: wheel-task-1
        python_wheel_task:
          entry_point: main
          package_name: wheel_package
        environment_key: Default

    environments:
      - environment_key: Default
        spec:
          client: "1"
          dependencies:
            - workflows_authoring_toolkit==0.0.1

targets:
  development:
    workspace:
      host: <workspace-url>

Consultez Exécuter votre tâche Azure Databricks avec un calcul serverless pour les flux de travail.

Partage via