Développer des pipelines Delta Live Tables avec des bundles de ressources Databricks

Article
10/14/2024

Les packs de ressources Databricks, également appelées packs, vous permettent de valider, déployer et exécuter programmatiquement des ressources Azure Databricks telles que des pipelines Delta Live Tables. Consultez Que sont les packs de ressources Databricks ?.

Cet article décrit comment créer un regroupement pour gérer un pipeline de manière programmatique. Consultez l’article Qu’est-ce que Delta Live Tables ?. Le regroupement est créé à l’aide du gabarit de regroupement par défaut de regroupements de ressources Databricks pour Python. Ces regroupements consistent en un notebook associé à la définition d’un pipeline et d’un projet pour l’exécuter. Vous validez ensuite, déployez et exécutez le pipeline déployé dans votre espace de travail Azure Databricks.

Conseil

Si vous avez des pipelines existants créés à l’aide de l’interface utilisateur ou de l’API Azure Databricks et que vous souhaitez les déplacer vers des regroupements, vous devez les définir dans les fichiers de configuration de regroupement. 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 supplémentaires, des notebooks et d’autres sources au regroupement. Consultez Ajouter une définition de pipeline existante à un regroupement.

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 distant doit disposer de fichiers d’espace de travail activés. Consultez l’article Que sont les fichiers d’espace de travail ?.

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

Databricks fournit un module Python pour accompagner le développement local de votre code de pipeline Delta Live Tables grâce à des fonctionnalités de vérification syntaxique, d’autocomplétion et de contrôle du type de données que vous pouvez activer 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 Stub Python pour Delta Live Tables.

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

Créez le regroupement en utilisant le gabarit de regroupement par défaut d’Azure Databricks pour Python. Ce gabarit consiste en un notebook qui définit un pipeline Delta Live Tables, qui filtre les données à partir du jeu de données original. 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 : Créer le pack

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 no , puis appuyez sur Enter. Cela indique à l’interface CLI Databricks de ne pas ajouter d’exemple de notebook à ce stade, car l’exemple de notebook associé à cette option n’a pas de code Delta Live Tables.
Pour Include a stub (sample) DLT pipeline, conservez la valeur par défaut yes en appuyant sur Enter. Cela indique à l’interface CLI Databricks d’ajouter un exemple de notebook contenant du code Delta Live Tables.
Pour Include a stub (sample) Python package, sélectionnez no , puis 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 pipeline et spécifie les paramètres relatifs à l’espace de travail cible.
resources/<project-name>_job.yml et resources/<project-name>_pipeline.yml : ces fichiers définissent le projet qui contient une tâche d’actualisation du pipeline et les paramètres du pipeline.
src/dlt_pipeline.ipynb: ce fichier est un notebook qui, lors de l’exécution, exécute le pipeline.

Pour la personnalisation des pipelines, les mappages dans une déclaration de pipeline correspondent à la charge utile de la demande de l'opération de création de pipeline telle que définie dans POST /api/2.0/pipelines dans la référence de l'API REST, exprimée au format YAML.

É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

Durant cette étape, vous déployez le notebook local dans votre espace de travail Azure Databricks distant et créez le pipeline Delta Live Tables 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 pipeline a été créé : dans la barre latérale de votre espace de travail Azure Databricks, cliquez sur Delta Live Tables.
Sous l’onglet Delta Live Tables , cliquez sur [dev <your-username>] <project-name>_pipeline.

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

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

Dans cette étape, vous déclenchez une exécution du pipeline Delta Live Tables 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>_pipeline
```
Copiez la valeur Update URL qui apparaît dans votre terminal et collez cette valeur dans votre navigateur web pour ouvrir votre espace de travail Azure Databricks.
Dans votre espace de travail Azure Databricks, une fois le pipeline terminé, cliquez sur l’affichage taxi_raw et l' filtered_taxis vue matérialisée pour afficher les détails.

Si vous apportez des modifications à votre offre groupée après cette étape, vous devez répéter les étapes 4-6 pour vérifier si votre configuration de pack est toujours valide, 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 pipeline 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 pipeline : 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 pipeline existante à un pack

Vous pouvez utiliser une définition de pipeline Delta Live Tables existante comme base pour définir un nouveau pipeline dans un fichier de configuration groupé. Pour obtenir une définition du pipeline 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 la CLI Databricks.

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

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

Dans la barre latérale de votre espace de travail Azure Databricks, cliquez sur Flux de travail.
Sous l’onglet Delta Live Tables, cliquez sur le lien Nom de votre pipeline.
En regard du bouton Développement, cliquez sur le kebab, puis cliquez sur Consulter les paramètres YAML.
Copiez le YAML de la définition du pipeline dans la boîte de dialogue Paramètres YAML du pipeline dans votre presse-papiers local en cliquant sur l’icône de copie.
Ajoutez le YAML que vous avez copié au fichier databricks.yml de votre regroupement, ou créez un fichier de configuration pour votre pipeline dans le dossier resources de votre projet de regroupement et faites-y référence à partir de votre fichier databricks.yml. Consultez Ressources.
Téléchargez et ajoutez tous les fichiers Python et les notebooks référencés dans la source du projet du 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 la définition de votre pipeline les référence correctement. Par exemple, pour un notebook nommé hello.ipynb qui se trouve dans l’annuaire src/ du regroupement :
```
resources:
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      libraries:
        - notebook:
            path: ../src/hello.ipynb
```

Générer une définition de pipeline existante à l’aide de CLI Databricks

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

Récupérez l’ID du pipeline existant à partir du panneau latéral Détails du pipeline pour le pipeline dans l’IU, ou utilisez la commande CLI Databricks databricks pipelines list-pipelines.
Exécutez la bundle generate pipeline commande CLI Databricks, en définissant l’ID de pipeline :
```
databricks bundle generate pipeline --existing-pipeline-id 6565621249
```
Cette commande crée un fichier de configuration regroupé pour le pipeline 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.

Partager via