Aller au contenu principal
Dernière mise à jour le

Utiliser dbx avec Visual Studio Code

important

Cette documentation a été retirée et pourrait ne pas être mise à jour.

Databricks vous recommande d’utiliser les Declarative Automation Bundles au lieu de dbx par Databricks Labs. Consultez Qu’est-ce que les Declarative Automation Bundles ? et Migrer de dbx vers des bundles.

Pour utiliser Databricks avec Visual Studio Code, consultez l'article Extension Databricks pour Visual Studio Code.

Cet article décrit un exemple de code basé sur Python avec lequel vous pouvez travailler dans n’importe quel IDE compatible Python. Plus précisément, cet article décrit comment travailler avec cet exemple de code dans Visual Studio Code, qui offre les fonctionnalités suivantes pour la productivité des développeurs :

Cet article utilise dbx par Databricks Labs, ainsi que Visual Studio Code, pour soumettre l'exemple de code à un workspace Databricks distant. dbx demande à Databricks via les Lakeflow Jobs d'exécuter le code soumis sur un cluster de jobs Databricks dans ce workspace.

Vous pouvez utiliser des fournisseurs Git tiers populaires pour le contrôle de version et les fonctionnalités d’intégration et de livraison continues (CI/CD) ou le déploiement continu de votre code. Pour le contrôle de version, ces fournisseurs Git incluent les suivants :

Pour le CI/CD, dbx prend en charge les plates-formes CI/CD suivantes :

Pour démontrer comment le contrôle de version et le CI/CD peuvent fonctionner, cet article décrit comment utiliser Visual Studio Code, dbx, et cet exemple de code, ainsi que GitHub et GitHub Actions.

Exigences relatives aux exemples de code​

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

  • Un Workspace Databricks dans votre compte Databricks.
  • Un compte GitHub. Créer un compte GitHub, si vous n’en avez pas déjà un.

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

  • Python version 3.8 ou supérieure.

    Vous devriez 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. Voir aussi la section «System environment» dans les Notes de version et compatibilité de Databricks Runtime pour la version de Databricks Runtime de vos clusters cibles. Dans tous les cas, la version de Python doit être 3.8 ou une version ultérieure.

    Pour obtenir la version de Python actuellement référencée sur votre machine locale, exécutez python --version depuis votre terminal local. (Selon la façon dont vous avez configuré Python sur votre machine locale, vous devrez peut-être exécuter python3 au lieu de python tout au long de cet article.) Voir aussi Sélectionner un interpréteur Python.

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

  • dbx version 0.8.0 ou supérieure. Vous pouvez installer le package dbx à partir de l’Index des packages Python (PyPI) en exécutant pip install dbx.

remarque

Vous n'avez pas besoin d'installer dbx maintenant. Vous pouvez l'installer ultérieurement dans la section configuration de l'exemple de code.

remarque

Vous n'avez pas besoin d'installer l'ancienne CLI Databricks (CLI Databricks version 0.17) maintenant. Vous pouvez l'installer plus tard dans la section configuration de l'exemple de code. Si vous souhaitez l'installer plus tard, vous devez vous rappeler de configurer l'authentification à ce moment-là.

À propos de l'exemple de code​

L'exemple de code Python pour cet article, disponible dans le dépôt databricks/ide-best-practices sur GitHub, effectue les opérations suivantes :

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

Configurer l'exemple de code​

Une fois que vous avez mis en place les exigences pour cet exemple de code, suivez les étapes suivantes pour commencer à l'utiliser.

remarque

Ces étapes n'incluent pas la configuration de cet exemple de code pour CI/CD. Vous n'avez pas besoin de configurer CI/CD pour exécuter cet exemple de code. Si vous souhaitez configurer CI/CD ultérieurement, consultez Exécuter avec GitHub Actions.

Étape 1 : créer un environnement virtuel Python​

  1. Depuis 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 donner à ce dossier le nom que vous souhaitez. Si vous utilisez un nom différent, remplacez le nom dans tout cet article. Après avoir créé le dossier, basculez vers celui-ci, puis start Visual Studio Code à partir de ce dossier. Assurez-vous d’inclure le point (.) après la commande code.

    Pour Linux et macOS :

    Bash
    mkdir ide-demo
    cd ide-demo
    code .
astuce

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

Pour Windows :

PowerShell
md ide-demo
cd ide-demo
code .

  1. Dans Visual Studio Code, dans la barre de menus, cliquez sur View > Terminal .

  2. Depuis 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.

    Bash
    pipenv --python <version>

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

  3. Sélectionnez l'interpréteur Python cible, puis activez l'environnement virtuel Python :

    1. Dans la barre de menus, cliquez sur Affichage > 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 est répertorié comme la 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 nouveau terminal .

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

      Bash
      pipenv shell

      Pour quitter le Shell pipenv, exécutez la commande exit, et les parenthèses disparaissent.

    Pour plus d'information, consultez Using Python environments in VS Code dans la documentation de Visual Studio Code.

Étape 2 : Cloner l'exemple de code 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**,Git: Clone tapez, puis cliquez sur **Git: Clone**.
  3. Pour fournir l’URL du repository ou choisir une source de repository , saisissez https://github.com/databricks/ide-best-practices
  4. Accédez à votre ide-demo dossier et cliquez sur **Sélectionner l'emplacement du repository**.

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

  1. Installez une version de dbx et de la CLI Databricks version 0,18 ou antérieure, compatible avec votre version de Python. Pour ce faire, dans Visual Studio Code, depuis votre terminal, depuis votre dossier ide-demo avec un Shell pipenv activé (pipenv shell), exécutez la commande suivante :

    Bash
    pip install dbx

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

    Bash
    dbx --version

    Si le numéro de version est renvoyé, 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 :

    Bash
    pip install dbx --upgrade
    dbx --version

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

  3. Lorsque vous installez dbx, l'ancienne CLI Databricks (CLI Databricks version 0,17) est également installée automatiquement. Pour confirmer que l'ancienne version de Databricks CLI (Databricks CLI version 0.17) est installée, exécutez la commande suivante :

    Bash
    databricks --version

    Si Databricks CLI version 0.17 est renvoyée, la version héritée de Databricks CLI est installée.

  4. Si vous n'avez pas configuré la CLI Databricks héritée (CLI Databricks version 0.17) avec l'authentification, vous devez le faire maintenant. Pour confirmer que l'authentification est configurée, exécutez la commande de base suivante afin d'obtenir des informations récapitulatives sur votre workspace Databricks. Assurez-vous d'inclure la barre oblique (/) après la sous-commande ls :

    Bash
    databricks workspace ls /

    Si une liste de noms de dossiers de niveau racine pour votre Workspace est renvoyé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 :

    Bash
    pip install -r unit-requirements.txt

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

    Bash
    pip list

    Si les packages qui figurent dans les fichiers requirements.txt et unit-requirements.txt se trouvent quelque part dans cette liste, les packages dépendants sont installés.

remarque

Les fichiers listés dans requirements.txt sont destinés à des versions de package spécifiques. Pour une meilleure compatibilité, vous pouvez croiser ces versions avec le type de nœud de cluster que vous souhaitez que votre Workspace Databricks utilise ultérieurement pour exécuter des déploiements. Consultez la section « Environnement système » pour connaître la version de Databricks Runtime de votre cluster dans Databricks Runtime : notes de publication, versions et compatibilité.

Étape 4 : Personnalisez l'exemple de code pour votre Workspace Databricks.​

  1. Personnalisez les paramètres de projet dbx du dépôt. Pour ce faire, dans le fichier .dbx/project.json, remplacez la valeur de l'objet profile de DEFAULT par le nom du profil qui correspond à celui que vous avez configuré pour l'authentification avec l'ancienne CLI Databricks (CLI Databricks version 0.17). Si vous n'avez pas configuré de profil non-default, laissez DEFAULT tel quel. Par exemple :

    JSON
    {
      "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 à la chaîne de version du runtime et au type de nœud de cluster Databricks que vous souhaitez que votre Workspace Databricks utilise pour l'exécution des déploiements.

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

    YAML
    environments:
      default:
        workflows:
          - name: 'covid_analysis_etl_integ'
            new_cluster:
              spark_version: '10.4.x-scala2.12'
              num_workers: 1
            node_type_id: 'i3.xlarge'
            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: 'i3.xlarge'
              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: 'i3.xlarge'
              spark_python_task:
                python_file: 'file://jobs/covid_trends_job_raw.py'
astuce

Dans cet exemple, chacune de ces trois définitions de job a la même valeur spark_version et node_type_id. Vous pouvez utiliser différentes valeurs pour différentes définitions de Job. Vous pouvez également créer des valeurs partagées et les réutiliser dans différentes définitions de job, afin de réduire les erreurs de saisie et la maintenance du code. Consultez l'exemple YAML dans la documentation dbx.

Explorer l'exemple de code​

Après avoir configuré l'exemple de code, utilisez les informations suivantes pour découvrir comment fonctionnent les 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 seul.

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é du fichier covid_analysis/transforms.py. Le fichier covid_analysis/__init__.py traite le dossier covide_analysis comme un package conteneur.

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 pour le fichier covid_analysis/transforms.py.

Programme d'exécution des tests unitaires​

Le fichier pytest.ini contient des options de configuration pour l'exécution des 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 la 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 de packages dont dépendent également les tests unitaires.

Packaging​

Le fichier setup.py fournit des commandes à exécuter dans la console (scripts de console), telles que la commande pip, pour empaqueter les projets Python avec setuptools. Voir les points d'entrée dans la documentation de 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 les GitHub Actions, abordées plus loin dans la section GitHub Actions.
  • Le fichier .gitignore contient une liste de dossiers et de fichiers locaux que Git ignore pour votre dépôt.

Exécutez l’exemple de code​

Vous pouvez utiliser dbx sur votre machine locale pour indiquer à Databricks d'exécuter l'exemple de code dans votre Workspace distant à la demande, comme décrit dans la sous-section suivante. Ou vous pouvez utiliser GitHub Actions pour que GitHub exécute l'exemple de code chaque fois que vous poussez des modifications de code vers votre dépôt GitHub.

Exécuter avec dbx​

  1. Installez le contenu du dossier covid_analysis en tant que package en Python setuptools en mode développement 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 :

    Bash
    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 :

    Bash
    pytest tests/

    Les résultats des tests s’affichent dans le terminal. Les quatre tests devraient s'afficher comme réussis.

astuce

Pour des approches supplémentaires en matière de tests, y compris les tests pour les Notebooks R et Scala, consultez Tests unitaires pour les Notebooks Databricks.

  1. Obtenez, en option, les métriques de couverture pour vos tests en exécutant la commande suivante :

    Bash
    coverage run -m pytest tests/
remarque

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

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

Bash
coverage report -m

  1. Si les quatre tests réussissent, envoyez le contenu du projet dbx à votre Workspace Databricks, en exécutant la commande suivante :

    Bash
    dbx deploy --environment=default

    Les informations sur le projet et ses exécutions sont envoyées à l'emplacement spécifié dans l'objet workspace_directory du fichier .dbx/project.json.

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

  2. Exécutez la version de préproduction du code dans votre Workspace, en exécutant la commande suivante :

    Bash
    dbx launch covid_analysis_etl_integ

    Un Link vers les résultats de l'exécution s'affiche dans le terminal. Cela devrait ressembler à ceci :

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

    Suivez ce Link dans votre navigateur web pour consulter les résultats de l'exécution dans votre Workspace.

  3. Exécutez la version de production du code dans votre Workspace, en exécutant la commande suivante :

    Bash
    dbx launch covid_analysis_etl_prod

    Un Link vers les résultats de l'exécution s'affiche dans le terminal. Cela devrait ressembler à ceci :

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

    Suivez ce Link dans votre navigateur web pour consulter les résultats de l'exécution dans votre Workspace.

Exécuter avec GitHub Actions​

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

  • À chaque envoi (push) vers une étiquette qui commence par v, utilise dbx pour déployer le job covid_analysis_etl_prod.
  • Sur chaque push qui n'est pas vers une balise commençant par v:
    1. Utilise pytest pour exécuter les tests unitaires.
    2. Utilise dbx pour déployer le fichier spécifié dans le Job covid_analysis_etl_integ vers le Workspace distant.
    3. Utilise dbx pour lancer le fichier déjà déployé spécifié dans le job covid_analysis_etl_integ sur le workspace distant, en traçant cette exécution jusqu'à ce qu'elle se termine.
remarque

Un fichier GitHub Actions supplémentaire, databricks_pull_request_tests.yml, vous est fourni en tant que template pour l'expérimentation, sans impacter les fichiers GitHub Actions onpush.yml et onrelease.yml. Vous pouvez exécuter cet exemple de code sans le fichier databricks_pull_request_tests.yml GitHub Actions. Son utilisation n'est pas couverte dans cet article.

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

Configurer pour utiliser GitHub Actions​

Configurez votre Workspace Databricks en suivant les instructions de la section Service Principals for CI/CD. Cela inclut les actions suivantes :

  1. Créer un Service Principal Databricks.
  2. Créez un jeton d'accès Databricks pour le Service Principal Databricks.

En tant que bonne pratique de sécurité, Databricks vous recommande d'utiliser un jeton d'accès Databricks pour un Service Principal Databricks, au lieu du jeton d'accès personnel Databricks pour votre utilisateur de Workspace, afin de permettre à GitHub de s'authentifier auprès de votre Workspace Databricks.

Après avoir créé le service principal Databricks et son jeton d'accès Databricks, arrêtez-vous et notez la valeur du jeton d'accès Databricks, que vous utiliserez dans la section suivante.

Exécuter GitHub Actions​

Étape 1 : Publier votre repo 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 d'abord l'extension GitHub Pull Requests and Issues via la vue Extensions ( Affichage > 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 Affichage > Palette de commandes , saisissez 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 : Ajoutez des secrets chiffrés à votre dépôt​

Dans le site web GitHub de votre repository publié, suivez les instructions de Création de secrets chiffrés pour un repository, pour les secrets chiffrés suivants :

  • Créez un secret chiffré nommé DATABRICKS_HOST, défini sur la valeur de l'URL de votre instance de Workspace, par exemple https://dbc-a1b2345c-d6e7.cloud.databricks.com.
  • Créez un secret chiffré nommé DATABRICKS_TOKEN, défini sur la valeur du jeton d'accès Databricks pour le service principal Databricks.
Étape 3 : Créer et publier une Branch vers votre repo​
  1. Dans Visual Studio Code, dans la vue Contrôle de code source ( Affichage > Contrôle de code source ), cliquez sur l'icône ... ( Vues et plus d'actions ).
  2. Cliquez sur **Branch > Créer une Branch à partir de**.
  3. Saisissez un nom pour la Branch, par exemple my-branch.
  4. Sélectionnez la branch à partir de laquelle créer la branch, par exemple main .
  5. Apportez une légère modification à l'un des fichiers de votre dépôt local, puis enregistrez le fichier. Par exemple, apportez une modification mineure à un commentaire de code dans le fichier tests/transforms_test.py.
  6. Dans la vue Contrôle de la source , cliquez à nouveau sur l'icône … ( Vues et autres actions ).
  7. Cliquez sur Modifications > Préparer toutes les modifications .
  8. Cliquez à nouveau sur l’icône **…** (**Vues et plus d’actions**).
  9. Cliquez sur Commit > Commit Staged .
  10. Saisissez un message pour le commit.
  11. Cliquez à nouveau sur l’icône **…** (**Vues et plus d’actions**).
  12. Cliquez sur **Branch > Publier la branche**.
Étape 4 : Créez une requête d'extraction et Merge​
  1. Accédez au site web GitHub pour votre référentiel publié, https://github/<your-GitHub-username>/ide-best-practices.
  2. Dans la **tab Pull requests**, à côté de **my-branch a eu des poussées récentes**, cliquez sur **Comparer et requête de tirage**.
  3. Cliquez sur **Créer une requête Pull**.
  4. Sur la page de la requête de tirage, attendez que l'icône à côté de CI pipleline / ci-pipeline (push) affiche une coche verte. (Cela peut prendre plusieurs minutes avant que l'icône n'apparaisse.) S'il y a une croix rouge au lieu d'une coche verte, cliquez sur Détails pour en connaître la raison. Si l'icône ou les **Détails** ne s'affichent plus, cliquez sur **Afficher toutes les vérifications**.
  5. Si la coche verte apparaît, Merge la pull request dans la main Branch en cliquant sur Merge pull request .
Sur cette page