Utiliser dbx avec Visual Studio Code

Pour illustrer comment cela peut fonctionner, cet article décrit un exemple de code basé sur Python que vous pouvez utiliser dans n’importe quel IDE compatible avec Python. Plus précisément, cet article explique comment utiliser cet exemple de code dans Visual Studio Code, qui fournit les fonctionnalités de productivité des développeurs suivantes :

• Complétion de code
• Linting
• Test
• Débogage d’objets de code qui ne nécessitent pas de connexion en temps réel à des ressources Azure Databricks distantes.

Cet article utilise des labos dbx par Databricks avec Visual Studio Code pour soumettre l’exemple de code à un espace de travail Azure Databricks distant. dbx demande à Azure Databricks de Planifier et orchestrer les flux de travail pour exécuter le code envoyé sur un groupement de projets Azure Databricks dans cet espace de travail.

Vous pouvez utiliser des fournisseurs Git tiers populaires pour la gestion de version ainsi que l’intégration continue et la livraison continue ou le déploiement continu (CI/CD) de votre code. Pour la gestion de version, ces fournisseurs Git incluent les suivants :

• GitHub
• Bitbucket
• GitLab
• Azure DevOps (non disponible dans les régions Azure Chine)
• AWS CodeCommit
• GitHub AE

Pour CI/CD, dbx prend en charge les plateformes CI/CD suivantes :

• Actions GitHub
• Azure Pipelines
• GitLab CI/CD

Pour illustrer le fonctionnement de la gestion de version et de CI/CD, cet article explique comment utiliser Visual Studio Code, dbx et cet exemple de code, ainsi que GitHub et GitHub Actions.

Configuration requise pour l’exemple de code

Pour utiliser cet exemple de code, vous devez disposer des éléments suivants :

• Un espace de travail Azure Databricks dans votre compte Azure Databricks.
• Un compte GitHub. Créez un compte GitHub, si vous n’en avez pas déjà un.

De plus, sur votre ordinateur de développement local, vous devez disposer des éléments suivants :

• Python version 3.8 ou ultérieure.

  Vous devez utiliser une version de Python qui correspond à celle installée sur vos clusters cibles. Pour obtenir la version de Python installée sur un cluster existant, vous pouvez utiliser le terminal web du cluster pour exécuter la commande python --version. Consultez également la section « Environnement système » dans les versions des notes de publication de Databricks Runtime et la compatibilité de la version de Databricks Runtime pour vos clusters cibles. Dans tous les cas, la version de Python doit être 3.8 ou ultérieure.

  Pour obtenir la version de Python actuellement référencée sur votre ordinateur local, exécutez python --version à partir de votre terminal local. (Selon la façon dont vous configurez Python sur votre ordinateur local, vous devrez peut-être exécuter python3 au lieu de python dans cet article). Voir aussi Sélectionner un interpréteur Python.

• pip. pip est automatiquement installé avec des versions plus récentes de Python. Pour vérifier si pip est déjà installé, exécutez pip --version à partir de votre terminal local. (Selon la façon dont vous configurez Python ou pip sur votre ordinateur local, vous devrez peut-être exécuter pip3 au lieu de pip dans cet article).

• Version dbx 0.8.0 ou ultérieure. Vous pouvez installer le package dbx à partir de Python Package Index (PyPI) en exécutant pip install dbx.

  Notes

  Il est inutile d’installer dbx maintenant. Vous pouvez l’installer ultérieurement dans la section de configuration de l’exemple de code.

• Une méthode pour créer des environnements virtuels Python afin de vous assurer que vous utilisez les bonnes versions de Python et dépendances de package dans vos projets dbx. Cet article couvre pipenv.

• L’interface CLI Databricks version 0.18 ou antérieure, configurée avec l’authentification.

  Remarque

  Vous n’avez pas besoin d’installer l’interface CLI Databricks héritée (Databricks CLI version 0.17) maintenant. Vous pouvez l’installer ultérieurement dans la section de configuration de l’exemple de code. Si vous souhaitez l’installer ultérieurement, vous devez vous rappeler de configurer l’authentification à ce moment-là.

• Visual Studio Code.

• Extension Python pour Visual Studio Code.

• Extension Demandes de tirage et problèmes GitHub pour Visual Studio Code.

• Git.

À propos de l’exemple de code

L’exemple de code Python pour cet article, disponible dans le référentiel databricks/ide-best-practices dans GitHub, effectue les opérations suivantes :

1. Obtient des données du référentiel owid/covid-19-data dans GitHub.
2. Filtre les données pour un code de pays ISO spécifique.
3. Crée un tableau croisé dynamique à partir des données.
4. Procède au nettoyage de données sur les données.
5. Modularise la logique de code en fonctions réutilisables.
6. Tests unitaires des fonctions.
7. Fournit des configurations et des paramètres de projet dbx pour permettre au code d’écrire les données dans une table Delta dans un espace de travail Azure Databricks distant.

Configuration de l’exemple de code

Lorsque les exigences pour cet exemple de code sont remplies, effectuez les étapes suivantes pour commencer à utiliser l’exemple de code.

Étape 1 : Créer un environnement virtuel Python

1. À partir de votre terminal, créez un dossier vide pour contenir un environnement virtuel pour cet exemple de code. Ces instructions utilisent un dossier parent nommé ide-demo. Vous pouvez attribuer le nom de votre choix à ce dossier. Si vous utilisez un autre nom, remplacez-le tout au long de cet article. Après avoir créé le dossier, basculez vers celui-ci, puis démarrez Visual Studio Code à partir de ce dossier. Veillez à inclure le point (.) après la commande code.

   Pour Linux et macOS :

   mkdir ide-demo
   cd ide-demo
   code .
   

   Conseil

   Si vous recevez l’erreur command not found: code, consultez Lancement à partir de la ligne de commande sur le site web Microsoft.

   Pour Windows :

   md ide-demo
   cd ide-demo
   code .
   

2. Dans Visual Studio Code, dans la barre de menus, cliquez sur Afficher > Terminal.

3. À partir de la racine du dossier ide-demo, exécutez la commande pipenv avec l’option suivante, où <version> est la version cible de Python que vous avez déjà installée localement (et, idéalement, une version qui correspond à la version de Python de vos clusters cibles), par exemple 3.8.14.

   pipenv --python <version>
   

   Notez la valeur Virtualenv location dans la sortie de la commande pipenv, car vous en aurez besoin à l’étape suivante.

4. Sélectionnez l’interpréteur Python cible, puis activez l’environnement virtuel Python :

   1. Dans la barre de menus, cliquez sur Afficher > Palette de commandes, tapez Python: Select, puis cliquez sur Python : Sélectionner l’interpréteur.

   2. Sélectionnez l’interpréteur Python dans le chemin d’accès à l’environnement virtuel Python que vous venez de créer. (Ce chemin d’accès est répertorié comme valeur Virtualenv location dans la sortie de la commande pipenv.)

   3. Dans la barre de menus, cliquez sur Afficher > Palette de commandes, tapez Terminal: Create, puis cliquez sur Terminal : Créer un terminal.

   4. Assurez-vous que l’invite de commandes indique que vous êtes dans l’interpréteur de commandes pipenv. Pour confirmer, vous devriez voir quelque chose comme (<your-username>) avant votre invite de commandes. Si vous ne le voyez pas, exécutez la commande suivante :

      pipenv shell
      

      Pour quitter l’interpréteur de commandes pipenv, exécutez la commande exit. Les parenthèses disparaissent.

   Pour plus d’informations, consultez Utilisation d’environnements Python dans VS Code dans la documentation Visual Studio Code.

Étape 2 : Cloner l’exemple de code à partir de GitHub

1. Dans Visual Studio Code, ouvrez le dossier ide-demo (Fichier > Ouvrir le dossier), s’il n’est pas déjà ouvert.
2. Cliquez sur Afficher > Palette de commandes, tapez Git: Clone, puis cliquez sur Git : Cloner.
3. Pour indiquer l'URL du référentiel ou choisir une source de référentiel, entrez https://github.com/databricks/ide-best-practices.
4. Accédez à votre dossier ide-demo, puis cliquez sur Sélectionner l’emplacement du référentiel.

Étape 3 : Installer les dépendances de l’exemple de code

1. Installez une version de dbx et l’interface CLI Databricks version 0.18 ou antérieure compatible avec votre version de Python. Pour ce faire, dans Visual Studio Code à partir de votre terminal, dans votre dossier ide-demo avec un interpréteur de commandes pipenv activé (pipenv shell), exécutez la commande suivante :

   pip install dbx
   

2. Vérifiez que dbx est installé. Pour ce faire, exécutez la commande suivante :

   dbx --version
   

   Si le numéro de version est retourné, dbx est installé.

   Si le numéro de version est inférieur à 0.8.0, mettez à niveau dbx en exécutant la commande suivante, puis vérifiez à nouveau le numéro de version :

   pip install dbx --upgrade
   dbx --version
   
   # Or ...
   python -m pip install dbx --upgrade
   dbx --version
   

3. Lorsque vous installez dbx, l’interface CLI Databricks héritée (Databricks CLI version 0.17) est également automatiquement installée. Pour vérifier que l’interface CLI Databricks héritée (Databricks CLI version 0.17) est installée, exécutez la commande suivante :

   databricks --version
   

   Si Databricks CLI version 0.17 est retournée, l’interface CLI Databricks héritée est installée.

4. Si vous n’avez pas configuré l’interface CLI Databricks héritée (Databricks CLI version 0.17) avec une authentification, vous devez le faire maintenant. Pour vérifier que l’authentification est configurée, exécutez la commande de base suivante pour obtenir des informations récapitulatives sur votre espace de travail Azure Databricks. Veillez à inclure la barre oblique (/) après la sous-commande ls :

   databricks workspace ls /
   

   Si une liste de noms de dossiers de niveau racine pour votre espace de travail est retournée, l’authentification est configurée.

5. Installez les packages Python dont dépend cet exemple de code. Pour ce faire, exécutez la commande suivante à partir du dossier ide-demo/ide-best-practices :

   pip install -r unit-requirements.txt
   

6. Vérifiez que les packages dépendants de l’exemple de code sont installés. Pour ce faire, exécutez la commande suivante :

   pip list
   

   Si les packages répertoriés dans les fichiers requirements.txt et unit-requirements.txt figurent dans cette liste, les packages dépendants sont installés.

   Notes

   Les fichiers répertoriés dans requirements.txt sont destinés à des versions de package spécifiques. Pour une meilleure compatibilité, vous pouvez faire référence à ces versions avec le type de nœud de cluster que vous souhaitez que votre espace de travail Azure Databricks utilise pour exécuter des déploiements ultérieurement. Consultez la section « Environnement système » pour la version Databricks Runtime de votre cluster dans les notes de publication sur les versions et la compatibilité de Databricks Runtime.

Étape 4 : Personnaliser l’exemple de code pour votre espace de travail Azure Databricks

1. Personnalisez les paramètres du projet dbx du référentiel. Pour ce faire, dans le fichier .dbx/project.json, remplacez la valeur DEFAULT de l’objet profile par le nom du profil qui correspond à celui que vous avez configuré pour l’authentification avec l’interface CLI Databricks héritée (Databricks CLI version 0.17). Si vous n’avez pas configuré de profil autre que celui par défaut, laissez DEFAULT tel quel. Par exemple :

   {
     "environments": {
       "default": {
         "profile": "DEFAULT",
         "storage_type": "mlflow",
         "properties": {
           "workspace_directory": "/Workspace/Shared/dbx/covid_analysis",
           "artifact_location": "dbfs:/Shared/dbx/projects/covid_analysis"
         }
       }
     },
     "inplace_jinja_support": false
   }
   

2. Personnalisez les paramètres de déploiement du projet dbx. Pour ce faire, dans le fichier conf/deployment.yml, modifiez la valeur des objets spark_version et node_type_id de 10.4.x-scala2.12 et m6gd.large par la chaîne de version du runtime Azure Databricks et le type de nœud de cluster que vous souhaitez que votre espace de travail Azure Databricks utilise pour exécuter des déploiements.

   Par exemple, pour spécifier Databricks Runtime 10.4 LTS et un type de nœud Standard_DS3_v2 :

   environments:
     default:
       workflows:
         - name: "covid_analysis_etl_integ"
           new_cluster:
             spark_version: "10.4.x-scala2.12"
             num_workers: 1
           node_type_id: "Standard_DS3_v2"
           spark_python_task:
             python_file: "file://jobs/covid_trends_job.py"
         - name: "covid_analysis_etl_prod"
           new_cluster:
             spark_version: "10.4.x-scala2.12"
             num_workers: 1
             node_type_id: "Standard_DS3_v2"
             spark_python_task:
               python_file: "file://jobs/covid_trends_job.py"
             parameters: ["--prod"]
         - name: "covid_analysis_etl_raw"
           new_cluster:
             spark_version: "10.4.x-scala2.12"
             num_workers: 1
             node_type_id: "Standard_DS3_v2"
             spark_python_task:
               python_file: "file://jobs/covid_trends_job_raw.py"
   

Explorer l’exemple de code

Après avoir configuré l’exemple de code, utilisez les informations suivantes pour en savoir plus sur le fonctionnement des différents fichiers du dossier ide-demo/ide-best-practices.

Modularisation du code

Code non modularisé

Le fichier jobs/covid_trends_job_raw.py est une version non modularisée de la logique de code. Vous pouvez exécuter ce fichier lui-même.

Code modularisé

Le fichier jobs/covid_trends_job.py est une version modularisée de la logique de code. Ce fichier s’appuie sur le code partagé dans le fichier covid_analysis/transforms.py. Le fichier covid_analysis/__init__.py traite le dossier covide_analysis comme un package contenant.

Test

Tests unitaires

Le fichier tests/testdata.csv contient une petite partie des données du fichier covid-hospitalizations.csv à des fins de test. Le fichier tests/transforms_test.py contient les tests unitaires du fichier covid_analysis/transforms.py.

Exécuteur de test unitaire

Le fichier pytest.ini contient des options de configuration pour l’exécution de tests avec pytest. Consultez pytest.ini et Options de configuration dans la documentation pytest.

Le fichier .coveragerc contient des options de configuration pour les mesures de couverture du code Python avec coverage.py. Consultez Informations de référence de configuration dans la documentation coverage.py.

Le fichier requirements.txt, qui est un sous-ensemble du fichier unit-requirements.txt que vous avez exécuté précédemment avec pip, contient une liste des packages dont dépendent également les tests unitaires.

Packaging

Le fichier setup.py fournit des commandes à exécuter au niveau de la console (scripts de console), telles que la commande pip, pour empaqueter des projets Python avec setuptools. Consultez Points d’entrée dans la documentation setuptools.

Autres fichiers

Il existe d’autres fichiers dans cet exemple de code qui n’ont pas été décrits précédemment :

• Le dossier .github/workflows contient trois fichiers, databricks_pull_request_tests.yml, onpush.yml et onrelease.yaml, qui représentent le GitHub Actions, qui sont abordés plus loin dans la section GitHub Actions.
• Le fichier .gitignore contient une liste de dossiers et fichiers locaux ignorés par Git pour votre référentiel.

Exécuter l’exemple de code

Vous pouvez utiliser dbx sur votre ordinateur local pour demander à Azure Databricks d’exécuter l’exemple de code dans votre espace de travail distant à la demande, comme décrit dans la sous-section suivante. Vous pouvez également utiliser GitHub Actions pour que GitHub exécute l’exemple de code chaque fois que vous envoyez des modifications de code à votre référentiel GitHub.

Exécuter avec dbx

1. Installez le contenu du dossier covid_analysis en tant que package en setuptools mode de développement Python en exécutant la commande suivante à partir de la racine de votre projet dbx (par exemple, le dossier ide-demo/ide-best-practices). Veillez à inclure le point (.) à la fin de cette commande :

   pip install -e .
   

   Cette commande crée un dossier covid_analysis.egg-info qui contient des informations sur la version compilée des fichiers covid_analysis/__init__.py et covid_analysis/transforms.py.

2. Exécutez les tests en exécutant la commande suivante :

   pytest tests/
   

   Les résultats des tests sont affichés dans le terminal. Les quatre tests doivent s’afficher comme réussis.

   Conseil

   Pour obtenir d’autres approches de test, notamment les tests pour les notebooks R et Scala, consultez Tests unitaires pour les notebooks.

3. Si vous le souhaitez, obtenez les mesures de couverture des tests pour vos tests en exécutant la commande suivante :

   coverage run -m pytest tests/
   

   Notes

   Si un message indique que coverage est introuvable, exécutez pip install coverage et réessayez.

   Pour afficher les résultats de la couverture des tests, exécutez la commande suivante :

   coverage report -m
   

4. Si les quatre tests réussissent, envoyez le contenu du projet dbx vers votre espace de travail Azure Databricks, en exécutant la commande suivante :

   dbx deploy --environment=default
   

   Les informations relatives au projet et à ses exécutions sont envoyées vers l’emplacement spécifié dans l’objet workspace_directory dans le fichier .dbx/project.json.

   Le contenu du projet est envoyé vers l’emplacement spécifié dans l’objet artifact_location dans le fichier .dbx/project.json.

5. Exécutez la version de préproduction du code dans votre espace de travail en exécutant la commande suivante :

   dbx launch covid_analysis_etl_integ
   

   Un lien vers les résultats de l’exécution s’affiche dans le terminal. Il doit se présenter comme suit :

   https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/12345
   

   Suivez ce lien dans votre navigateur web pour afficher les résultats de l’exécution dans votre espace de travail.

6. Exécutez la version de production du code dans votre espace de travail en exécutant la commande suivante :

   dbx launch covid_analysis_etl_prod
   

   Un lien vers les résultats de l’exécution s’affiche dans le terminal. Il doit se présenter comme suit :

   https://<your-workspace-instance-id>/?o=1234567890123456#job/123456789012345/run/23456
   

   Suivez ce lien dans votre navigateur web pour afficher les résultats de l’exécution dans votre espace de travail.

Exécuter avec GitHub Actions

Dans le dossier du projet .github/workflows, les fichiers GitHub Actions onpush.yml et onrelease.yml effectuent les opérations suivantes :

• À chaque envoi (push) vers une balise qui commence par v, utilise dbx pour déployer le travail covid_analysis_etl_prod.
• À chaque envoi (push) qui n’est pas à une balise qui commence par v :
  1. Utilise pytest pour exécuter les tests unitaires.
  2. Utilise dbx pour déployer le fichier spécifié dans le travail covid_analysis_etl_integ dans l’espace de travail distant.
  3. Utilise dbx pour lancer le fichier déjà déployé spécifié dans le travail covid_analysis_etl_integ dans l’espace de travail distant, suivant ainsi cette exécution jusqu’à ce qu’elle se termine.

Les sous-sections suivantes décrivent comment configurer et exécuter les fichiers GitHub Actions onpush.yml et onrelease.yml.

Configurer pour utiliser GitHub Actions

Configurez votre espace de travail Azure Databricks en suivant les instructions fournies dans Principaux de service pour CI/CD. Cette opération inclut les actions suivantes :

1. Créer un principal de service.
2. Créez un jeton Microsoft Entra ID pour le principal de service.

À titre de bonne pratique de sécurité, Databricks vous recommande d’utiliser un jeton Microsoft Entra ID pour un principal de service, au lieu du jeton d’accès personnel Databricks pour l’utilisateur de votre espace de travail, afin de permettre à GitHub de s’authentifier auprès de votre espace de travail Azure Databricks.

Après avoir créé le principal de service et son jeton Microsoft Entra ID, arrêtez-vous un instant et relevez la valeur du jeton Microsoft Entra ID à utiliser dans la section suivante.

Exécuter GitHub Actions

Étape 1 : Publier votre référentiel cloné

1. Dans Visual Studio Code, dans la barre latérale, cliquez sur l’icône GitHub. Si l’icône n’est pas visible, activez tout d’abord l’extension Demandes de tirage et problèmes GitHub par le biais de l’affichage Extensions (Afficher > Extensions).
2. Si le bouton Se connecter est visible, cliquez dessus et suivez les instructions à l’écran pour vous connecter à votre compte GitHub.
3. Dans la barre de menus, cliquez sur Afficher > Palette de commandes, tapez Publish to GitHub, puis cliquez sur Publier sur GitHub.
4. Sélectionnez une option pour publier votre référentiel cloné sur votre compte GitHub.

Étape 2 : Ajouter des secrets chiffrés à votre référentiel

Sur le site web GitHub de votre référentiel publié, suivez les instructions fournies dans Création de secrets chiffrés pour un référentiel, pour les secrets chiffrés suivants :

• Créez un secret chiffré nommé DATABRICKS_HOST et définissez-le sur la valeur de votre URL par espace de travail, par exemple https://adb-1234567890123456.7.azuredatabricks.net.
• Créez un secret chiffré nommé DATABRICKS_TOKEN et définissez-le sur la valeur du jeton Microsoft Entra ID pour le principal de service.

Étape 3 : Créer et publier une branche dans votre référentiel

1. Dans Visual Studio Code, dans l’affichage Contrôle de code source (Afficher > Contrôle de code source), cliquez sur l’icône ... (Affichages et plus d’actions).
2. Cliquez sur Branche > Créer une branche à partir de.
3. Entrez un nom pour la branche, par exemple my-branch .
4. Sélectionnez la branche à partir de laquelle créer la branche, par exemple main.
5. Apportez une modification mineure à l’un des fichiers de votre référentiel local, puis enregistrez le fichier. Par exemple, apportez une modification mineure à un commentaire de code dans le fichier tests/transforms_test.py.
6. Dans l’affichage Contrôle de code source, cliquez à nouveau sur l’icône ... (Affichages et plus d’actions).
7. Cliquez sur Modifications > Indexer toutes les modifications.
8. Cliquez à nouveau sur l’icône ... (Affichages et plus d’actions).
9. Cliquez sur Valider > Valider les modifications en attente.
10. Entrez un message pour la validation.
11. Cliquez à nouveau sur l’icône ... (Affichages et plus d’actions).
12. Cliquez sur Branche > Publier la branche.

Étape 4 : Créer une demande de tirage et une fusion

1. Accédez au site web GitHub de votre référentiel publié, https://github/<your-GitHub-username>/ide-best-practices.
2. Sous l’onglet Demandes de tirage (pull requests), en regard de my-branch had recent pushes, cliquez sur Comparer et demande de tirage (pull request).
3. Cliquez sur Créer une demande de tirage.
4. Dans la page de demande de tirage, attendez que l’icône en regard de pipeline CI / ci-pipeline (push) affiche une coche verte. (Cela peut prendre quelques minutes avant que l’icône n’apparaisse.) Si un X rouge apparaît au lieu d’une coche verte, cliquez sur Détails pour en connaître la raison. Si l’icône ou Détails n’apparaissent plus, cliquez sur Afficher toutes les vérifications.
5. Si la coche verte s’affiche, fusionnez la demande de tirage dans la branche main en cliquant sur Fusionner la demande de tirage.