Aller au contenu principal
Dernière mise à jour le

Bonnes pratiques d'ingénierie logicielle pour les Notebooks Databricks

Appliquez les meilleures pratiques d’ingénierie logicielle à vos Notebooks Databricks : contrôle de version, partage de code, test et éventuellement fonctionnalités d’intégration et de livraison continues (CI/CD) ou déploiement (CI/CD).

Dans cette présentation, vous :

  • Ajoutez des Notebooks aux dossiers Git Databricks pour le contrôle de version.
  • Extrayez des portions de code de l'un des notebooks dans un module partageable.
  • Testez le code partagé.
  • Exécutez les Notebooks à partir d'un job Databricks.
  • Appliquez éventuellement le CI/CD au code partagé.

Exigences​

Pour terminer cette présentation, vous devez fournir les Ressources suivantes :

  • Un remote repository avec un fournisseur Git que Databricks prend en charge. Le guide pas à pas de cet article utilise GitHub. Ce guide pas à pas suppose que vous disposez d'un repository GitHub nommé best-notebooks. (Vous pouvez donner un nom différent à votre repository.) Si c’est le cas, remplacez best-notebooks par le nom de votre dépôt tout au long de cette procédure pas à pas.) Créez un dépôt GitHub si vous n'en avez pas déjà un.
remarque

Si vous créez un nouveau repository, assurez-vous d'initialiser le repository avec au moins un fichier, par exemple un fichier README.

Étape 1 : Configurez les dossiers Git Databricks​

Dans cette étape, vous connectez votre dépôt GitHub existant aux dossiers Git Databricks dans votre Workspace Databricks existant.

Pour permettre à votre Workspace de se connecter à votre dépôt GitHub, vous devez d'abord fournir à votre Workspace vos informations d'identification GitHub, si vous ne l'avez pas déjà fait.

Étape 1.1 : Fournir vos identifiants GitHub​

  1. Cliquez sur votre nom d'utilisateur en haut à droite du {glossary:Workspace}, puis cliquez sur Paramètres dans la liste déroulante.
  2. Dans la barre latérale Paramètres , sous Utilisateur , cliquez sur Comptes liés .
  3. Sous Intégration Git , pour fournisseur Git , sélectionnez GitHub .
  4. Cliquez sur Jeton d'accès personnel .
  5. Pour Nom d'utilisateur ou e-mail du fournisseur Git , entrez votre nom d'utilisateur GitHub.
  6. Pour **Jeton**, saisissez votre jeton d'accès personnel GitHub (classic). Ce jeton d'accès personnel (classique) doit disposer des autorisations de repository et de workflow .
  7. Cliquez sur Enregistrer .

Étape 1.2 : Connectez-vous à votre dépôt GitHub​

  1. Dans la barre latérale du Workspace, cliquez sur Workspace .
  2. Dans le navigateur Workspace , développez Workspace > Users .
  3. Faites un clic droit sur votre dossier d'utilisateur, puis cliquez sur Créer > Dossier Git .
  4. Dans la boîte de dialogue Créer un dossier Git :
    1. Pour l'URL du **Git repository**, saisissez l'URL de clonage avec HTTPS de votre GitHub repo. Cet article suppose que votre URL se termine par best-notebooks.git, par exemple https://github.com/<your-GitHub-username>/best-notebooks.git.
    2. Pour le **fournisseur Git**, sélectionnez **GitHub**.
    3. Laissez Nom du dossier Git défini sur le nom de votre repo, par exemple best-notebooks.
    4. Cliquez sur Créer un dossier Git .

Étape 2 : importer et exécuter le notebook​

À cette étape, vous importez un Notebook externe existant dans votre repo. Vous pourriez créer vos propres Notebooks pour cette présentation, mais pour accélérer les choses, nous vous les fournissons ici.

Étape 2.1 : Créer une Branch de travail dans le dépôt​

Dans cette sous-étape, vous créez une Branch nommée eda dans votre dépôt. Cette Branch vous permet de travailler sur les fichiers et le code indépendamment de la Branch main de votre dépôt, ce qui est une bonne pratique en matière d'ingénierie logicielle. (Vous pouvez donner un nom différent à votre Branch.)

remarque

Dans certains repos, la Branch main peut être nommée master à la place. Si tel est le cas, remplacez main par master dans ce guide.

astuce

Si vous n'êtes pas familier avec l'utilisation des Git Branch, consultez Git Branch – Les Branch en bref sur le site web de Git.

  1. Le dossier Git de l'étape 1.2 devrait être ouvert. Si ce n'est pas le cas, alors dans la barre latérale Workspace , développez Workspace > Utilisateurs , puis développez votre dossier de nom d'utilisateur et cliquez sur votre dossier Git.

  2. À côté du nom du dossier sous le fil d'Ariane de navigation du Workspace, cliquez sur le bouton de la Git **Branch** principale.

  3. Dans la boîte de dialogue best-notebooks , cliquez sur le bouton Créer une Branch .

remarque

Si votre référentiel a un nom autre que best-notebooks, le titre de cette boîte de dialogue sera différent, ici et tout au long de cette présentation.

  1. Saisissez eda, puis cliquez sur Créer .

  2. Fermez cette boîte de dialogue.

Étape 2.2 : Importez le Notebook dans le référentiel​

Dans cette sous-étape, vous importez un Notebook existant d'un autre référentiel dans votre référentiel. Ce Notebook effectue les opérations suivantes :

  • Copie un fichier CSV depuis le repository GitHub owid/covid-19-data sur un cluster dans votre Workspace. Ce fichier CSV contient des données publiques concernant les hospitalisations et les indicateurs de soins intensifs liés à la COVID-19 du monde entier.
  • Lit le contenu du fichier CSV dans un pandas DataFrame.
  • Filtre les données pour ne contenir que les métriques des États-Unis.
  • Affiche un tracé des données.
  • Enregistre le DataFrame pandas en tant que API Pandas sur Spark DataFrame.
  • Effectue le nettoyage de données sur le DataFrame de l'API Pandas sur Spark.
  • Écrit l'API Pandas sur Spark DataFrame en tant que table Delta dans votre Workspace.
  • Affiche le contenu de la table Delta.

Bien que vous puissiez créer votre propre Notebook ici dans votre référentiel, l'importation d'un Notebook existant contribue à accélérer cette présentation. Pour créer un notebook dans cette Branch ou déplacer un notebook existant dans cette Branch au lieu d'importer un notebook, consultez Utilisation de base des fichiers Workspace.

  1. À partir du dossier Git best-notebooks , cliquez sur Créer > Dossier .
  2. Dans la boîte de dialogue **Nouveau dossier**,notebooks saisissez, puis cliquez sur **Créer**.
  3. Depuis le dossier notebooks , cliquez sur les points de suspension, puis sur Importer .
  4. Dans la boîte de dialogue Importation :

    1. Pour Importer depuis , sélectionnez URL .

    2. Saisissez l'URL des contenus bruts du notebook covid_eda_raw du dépôt databricks/notebook-best-practices sur GitHub. Pour obtenir cette URL : i. Accédez à https://github.com/databricks/notebook-best-practices. ii. Cliquez sur le notebooks dossier. iii. Cliquez sur le fichier covid_eda_raw.py. iv. Cliquez sur Brut . v. Copiez l'URL complète depuis la barre d'adresse de votre navigateur web dans la boîte de dialogue Importation .

remarque

La boîte de dialogue Importation fonctionne uniquement avec les URL Git pour les repository publics.

  1. Cliquez sur **Importer**.

Étape 2.3 : Exécuter le Notebook​

  1. Si le Notebook n'apparaît pas déjà, ouvrez le dossier notebooks , puis cliquez sur le Notebook covid_eda_raw à l'intérieur du dossier.
  2. Sélectionnez le cluster auquel associer ce Notebook. Pour obtenir des instructions sur la création d'un cluster, consultez Créer un cluster.
  3. Cliquez sur **Tout exécuter**.
  4. Veuillez patienter pendant que le notebook s'exécute.

Une fois le Notebook terminé, dans le Notebook, vous devriez voir un graphique des données ainsi que plus de 600 lignes de données brutes dans la table Delta. Si le cluster n’était pas déjà en cours d’exécution lorsque vous avez start running ce Notebook, le cluster pourrait prendre plusieurs minutes à start up avant d’afficher les résultats.

Étape 2.4 : archiver et Merge le notebook​

Dans cette sous-étape, vous enregistrez votre travail jusqu'à présent dans votre référentiel GitHub. Vous Merge ensuite le Notebook de votre Branch de travail dans la Branch main de votre référentiel.

  1. À côté du nom du notebook, cliquez sur le bouton de la Git Branch eda.
  2. Dans la boîte de dialogue **best-notebooks**, sous l'onglet tab **Modifications**, assurez-vous que le fichier **notebooks/covid_eda_raw.py** est sélectionné.
  3. Pour le message de commit (nécessaire) , saisissez Added raw notebook.
  4. Pour **Description (facultatif)**, saisissez This is the first version of the notebook.
  5. Cliquez sur Commit & Push .
  6. Cliquez sur le Link de la requête d'extraction dans Créer une requête d'extraction sur votre fournisseur Git dans la bannière.
  7. Dans GitHub, créez la pull request, puis fusionnez la pull request dans la branch main.
  8. De retour dans votre Workspace Databricks, fermez la boîte de dialogue best-notebooks si elle est toujours affichée.

Étape 3 : Déplacer le code vers un module partagé​

À cette étape, vous déplacez une partie du code de votre Notebook dans un ensemble de fonctions partagées en dehors de votre Notebook. Cela vous permet d'utiliser ces fonctions avec d'autres notebooks similaires, ce qui peut accélérer le codage futur et contribuer à garantir des résultats de notebook plus prévisibles et cohérents. Le partage de ce code vous permet également de tester plus facilement ces fonctions, ce qui, en tant que bonne pratique de génie logiciel, peut améliorer la qualité globale de votre code au fur et à mesure.

Étape 3.1 : Créez une autre Branch de travail dans le référentiel.​

  1. À côté du nom du notebook, cliquez sur le bouton de la Git Branch eda.
  2. Dans la boîte de dialogue best-notebooks , cliquez sur la flèche déroulante à côté de la branch eda et sélectionnez main .
  3. Cliquez sur le bouton **Tirer**. Si vous êtes invité(e) à procéder à l'extraction, cliquez sur **Confirmer**.
  4. Cliquez sur le bouton Créer une Branch .
  5. Saisissez first_modules, puis cliquez sur Créer . (Vous pouvez donner un nom différent à votre Branch.)
  6. Fermez cette boîte de dialogue.

Étape 3.2 : Importer le notebook dans le référentiel​

Pour accélérer cette présentation, dans cette sous-étape, vous importez un autre Notebook existant dans votre dépôt. Ce Notebook fait les mêmes choses que le Notebook précédent, sauf que ce Notebook appellera des fonctions de code partagé qui sont stockées en dehors du Notebook. Encore une fois, vous pouvez créer votre propre Notebook dans votre référentiel ici et effectuer le partage de code vous-même.

  1. Depuis le navigateur Workspace , cliquez avec le bouton droit sur le dossier Notebooks , puis cliquez sur Importer .
  2. Dans la boîte de dialogue Importation :

    1. Pour Importer depuis , sélectionnez URL .

    2. Saisissez l'URL des contenus bruts du notebook covid_eda_modular du dépôt databricks/notebook-best-practices sur GitHub. Pour obtenir cette URL : i. Accédez à https://github.com/databricks/notebook-best-practices. ii. Cliquez sur le notebooks dossier. iii. Cliquez sur le fichier covid_eda_modular.py. iv. Cliquez sur Brut . v. Copiez l'URL complète depuis la barre d'adresse de votre navigateur web dans la boîte de dialogue Importer des Notebooks .

remarque

La boîte de dialogue Importer des Notebooks fonctionne avec les URL Git pour les repository publics uniquement.

  1. Cliquez sur **Importer**.

Étape 3.3 : Ajoutez les fonctions de code partagé de support du notebook​

  1. Dans le navigateur Workspace , cliquez avec le bouton droit sur le dossier Git best-notebooks , puis cliquez sur Créer > Dossier .

  2. Dans la boîte de dialogue **Nouveau dossier**,covid_analysis saisissez, puis cliquez sur **Créer**.

  3. Depuis le dossier covid_analysis , cliquez sur Créer > Fichier .

  4. Dans la boîte de dialogue Nouveau nom de fichier , entrez transforms.py, puis cliquez sur Créer le fichier .

  5. Dans la fenêtre de l’éditeur transforms.py , saisissez le code suivant :

    Python
    import pandas as pd

    # Filter by country code.
    def filter_country(pdf, country="USA"):
      pdf = pdf[pdf.iso_code == country]
      return pdf

    # Pivot by indicator, and fill missing values.
    def pivot_and_clean(pdf, fillna):
      pdf["value"] = pd.to_numeric(pdf["value"])
      pdf = pdf.fillna(fillna).pivot_table(
        values="value", columns="indicator", index="date"
      )
      return pdf

    # Create column names that are compatible with Delta tables.
    def clean_spark_cols(pdf):
      pdf.columns = pdf.columns.str.replace(" ", "_")
      return pdf

    # Convert index to column (works with pandas API on Spark, too).
    def index_to_col(df, colname):
      df[colname] = df.index
      return df
astuce

Pour d'autres techniques de partage de code, consultez Partager du code entre des Notebooks Databricks.

Étape 3.4 : Ajoutez les dépendances du code partagé​

Le code précédent a plusieurs dépendances de Python package pour permettre l'exécution correcte du code. Dans cette sous-étape, vous déclarez ces dépendances de package. La déclaration des dépendances améliore la reproductibilité en utilisant des versions de bibliothèques définies avec précision.

  1. Dans le navigateur Workspace , cliquez avec le bouton droit sur le dossier Git best-notebooks , puis cliquez sur Créer > Fichier .
remarque

Vous voulez que le fichier qui répertorie les dépendances de package aille à la racine du dossier Git, pas dans les dossiers notebooks ou covid_analysis .

  1. Dans la boîte de dialogue Nouveau nom de fichier , entrez requirements.txt, puis cliquez sur Créer le fichier .

  2. Dans la fenêtre de l'éditeur requirements.txt , saisissez le code suivant :

remarque

Si le fichier requirements.txt n'est pas visible, vous devrez peut-être refresh votre navigateur web.

Text
-i https://pypi.org/simple
attrs==21.4.0
cycler==0.11.0
fonttools==4.33.3
iniconfig==1.1.1
kiwisolver==1.4.2
matplotlib==3.5.1
numpy==1.22.3
packaging==21.3
pandas==1.4.2
pillow==9.1.0
pluggy==1.0.0
py==1.11.0
py4j==0.10.9.3
pyarrow==7.0.0
pyparsing==3.0.8
pyspark==3.2.1
pytest==7.1.2
python-dateutil==2.8.2
pytz==2022.1
six==1.16.0
tomli==2.0.1
wget==3.2
remarque

Le fichier précédent répertorie des versions de package spécifiques. Pour une meilleure compatibilité, vous pouvez comparer ces versions avec celles qui sont installées sur votre cluster polyvalent. Consultez la section « Environnement système » pour connaître la version de Databricks Runtime de votre cluster dans les notes de version et la compatibilité de Databricks Runtime.

Votre structure de dépôt devrait maintenant ressembler à ceci :

Text
|-- covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  └── covid_eda_raw (optional)
└── requirements.txt

Étape 3.5 : exécutez le Notebook refactorisé.​

Dans cette sous-étape, vous exécutez le Notebook covid_eda_modular, qui appelle le code partagé dans covid_analysis/transforms.py.

  1. Depuis le navigateur **Workspace**, cliquez sur le notebook **covid_eda_modular** dans le dossier **notebooks**.
  2. Sélectionnez le cluster auquel associer ce notebook.
  3. Cliquez sur **Tout exécuter**.
  4. Veuillez patienter pendant que le notebook s'exécute.

Une fois que le Notebook a fini de s'exécuter, vous devriez voir des résultats similaires à ceux du Notebook covid_eda_raw : un tracé des données ainsi que plus de 600 lignes de données brutes dans la table Delta. La principale différence avec ce Notebook est qu'un filtre différent est utilisé (un iso_code de DZA au lieu de USA). Si le cluster n'était pas déjà en cours d'exécution lorsque vous avez commencé à exécuter ce Notebook, cela pourrait prendre plusieurs minutes pour que le cluster start avant d'afficher les résultats.

Étape 3.6 : Validez le Notebook et son code associé​

  1. À côté du nom du Notebook, cliquez sur le bouton de la Branch Git first_modules .

  2. Dans la boîte de dialogue best-Notebooks , sur le Changes tab , assurez-vous que les éléments suivants sont sélectionnés :

    • requirements.txt
    • covid_analysis/transforms.py
    • notebooks/covid_eda_modular.py

  3. Pour le message de commit (nécessaire) , saisissez Added refactored notebook.

  4. Pour **Description (facultatif)**, saisissez This is the second version of the notebook.

  5. Cliquez sur Commit & Push .

  6. Cliquez sur le Link de la requête d'extraction dans Créer une requête d'extraction sur votre fournisseur Git dans la bannière.

  7. Dans GitHub, créez la pull request, puis fusionnez la pull request dans la branch main.

  8. De retour dans votre Workspace Databricks, fermez la boîte de dialogue best-notebooks si elle est toujours affichée.

Étape 4 : Tester le code partagé​

À cette étape, vous testez le code partagé de la dernière étape. Cependant, vous souhaitez tester ce code sans exécuter le notebook covid_eda_modular lui-même. En effet, si le code partagé ne parvient pas à s’exécuter, le Notebook lui-même échouerait probablement également. Vous souhaitez d'abord détecter les défaillances de votre code partagé avant que votre notebook principal ne finisse par échouer plus tard. Cette technique de test est une bonne pratique d’ingénierie logicielle.

astuce

Pour d'autres approches de tests pour les Notebooks, ainsi que pour les Notebooks R et Scala, consultez Tests unitaires pour les Notebooks Databricks.

Étape 4.1 : Créez une autre Branch de travail dans le référentiel​

  1. À côté du nom du Notebook, cliquez sur le bouton de la Branch Git first_modules .
  2. Dans la boîte de dialogue **best-notebooks**, cliquez sur la flèche déroulante à côté de la Branch **first_modules**, et sélectionnez **main**.
  3. Cliquez sur le bouton **Tirer**. Si vous êtes invité(e) à procéder à l'extraction, cliquez sur **Confirmer**.
  4. Cliquez sur Créer une Branch .
  5. Saisissez first_tests, puis cliquez sur Créer . (Vous pouvez donner un nom différent à votre Branch.)
  6. Fermez cette boîte de dialogue.

Étape 4.2 : Ajoutez les tests​

Dans cette sous-étape, vous utilisez le cadre pytest pour tester votre code partagé. Dans ces tests, vous affirmez si des résultats de test particuliers sont obtenus. Si un test produit un résultat inattendu, ce test particulier échoue à l'assertion et donc le test lui-même échoue.

  1. À partir du navigateur Workspace , cliquez avec le bouton droit sur votre dossier Git, puis cliquez sur Créer > Dossier .

  2. Dans la boîte de dialogue **Nouveau dossier**,tests saisissez, puis cliquez sur **Créer**.

  3. Dans le dossier **tests**, cliquez sur **Créer > Fichier**.

  4. Dans la boîte de dialogue Nouveau nom de fichier , entrez testdata.csv, puis cliquez sur Créer le fichier .

  5. Dans la fenêtre de l'éditeur **testdata.csv**, saisissez les données de test suivantes :

    entity,iso_code,date,indicator,value
    United States,USA,2022-04-17,Daily ICU occupancy,
    United States,USA,2022-04-17,Daily ICU occupancy per million,4.1
    United States,USA,2022-04-17,Daily hospital occupancy,10000
    United States,USA,2022-04-17,Daily hospital occupancy per million,30.3
    United States,USA,2022-04-17,Weekly new hospital admissions,11000
    United States,USA,2022-04-17,Weekly new hospital admissions per million,32.8
    Algeria,DZA,2022-04-18,Daily ICU occupancy,1010
    Algeria,DZA,2022-04-18,Daily ICU occupancy per million,4.5
    Algeria,DZA,2022-04-18,Daily hospital occupancy,11000
    Algeria,DZA,2022-04-18,Daily hospital occupancy per million,30.9
    Algeria,DZA,2022-04-18,Weekly new hospital admissions,10000
    Algeria,DZA,2022-04-18,Weekly new hospital admissions per million,32.1

  6. Dans le dossier **tests**, cliquez sur **Créer > Fichier**.

  7. Dans la boîte de dialogue Nouveau nom de fichier , entrez transforms_test.py, puis cliquez sur Créer le fichier .

  8. Dans la fenêtre de l'éditeur **transforms_test.py**, saisissez le code de test suivant. Ces tests utilisent des pytest fixtures standard ainsi qu'un DataFrame pandas simulé en mémoire :

    Python
    # Test each of the transform functions.
    import pytest
    from textwrap import fill
    import os
    import pandas as pd
    import numpy as np
    from covid_analysis.transforms import *
    from pyspark.sql import SparkSession

    @pytest.fixture
    def raw_input_df() -> pd.DataFrame:
      """
      Create a basic version of the input dataset for testing, including NaNs.
      """
      return pd.read_csv('tests/testdata.csv')

    @pytest.fixture
    def colnames_df() -> pd.DataFrame:
      df = pd.DataFrame(
        data=[[0,1,2,3,4,5]],
        columns=[
          "Daily ICU occupancy",
          "Daily ICU occupancy per million",
          "Daily hospital occupancy",
          "Daily hospital occupancy per million",
          "Weekly new hospital admissions",
          "Weekly new hospital admissions per million"
        ]
      )
      return df

    # Make sure the filter works as expected.
    def test_filter(raw_input_df):
      filtered = filter_country(raw_input_df)
      assert filtered.iso_code.drop_duplicates()[0] == "USA"

    # The test data has NaNs for Daily ICU occupancy; this should get filled to 0.
    def test_pivot(raw_input_df):
      pivoted = pivot_and_clean(raw_input_df, 0)
      assert pivoted["Daily ICU occupancy"][0] == 0

    # Test column cleaning.
    def test_clean_cols(colnames_df):
      cleaned = clean_spark_cols(colnames_df)
      cols_w_spaces = cleaned.filter(regex=(" "))
      assert cols_w_spaces.empty == True

    # Test column creation from index.
    def test_index_to_col(raw_input_df):
      raw_input_df["col_from_index"] = raw_input_df.index
      assert (raw_input_df.index == raw_input_df.col_from_index).all()

Votre structure de dépôt devrait maintenant ressembler à ceci :

Text
├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  └── covid_eda_raw (optional)
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py

Étape 4.3 : Exécuter les tests​

Pour accélérer cette démonstration, dans cette sous-étape, vous utilisez un notebook importé pour exécuter les tests précédents. Ce Notebook download et installe les packages Python dépendants des tests dans votre Workspace, exécute les tests et rapporte les résultats des tests. Bien que vous puissiez exécuter pytest depuis le terminal web de votre cluster, l'exécution de pytest à partir d'un notebook peut être plus pratique.

remarque

L'exécution de pytest exécute tous les fichiers dont les noms suivent le format test_*.py ou /*_test.py dans le répertoire actuel et ses sous-répertoires.

  1. Depuis le navigateur Workspace , cliquez avec le bouton droit sur le dossier Notebooks , puis cliquez sur Importer .

  2. Dans la boîte de dialogue **Importer des notebooks** :

    1. Pour Importer depuis , sélectionnez URL .

    2. Saisissez l'URL des contenus bruts du notebook run_unit_tests du dépôt databricks/notebook-best-practices sur GitHub. Pour obtenir cette URL : i. Accédez à https://github.com/databricks/notebook-best-practices. ii. Cliquez sur le notebooks dossier. iii. Cliquez sur le fichier run_unit_tests.py. iv. Cliquez sur Brut . v. Copiez l'URL complète depuis la barre d'adresse de votre navigateur web dans la boîte de dialogue Importer des Notebooks .

remarque

La boîte de dialogue Importer des Notebooks fonctionne avec les URL Git pour les repository publics uniquement.

  1. Cliquez sur **Importer**.

  2. Sélectionnez le cluster auquel associer ce notebook.

  3. Cliquez sur **Tout exécuter**.

  4. Veuillez patienter pendant que le notebook s'exécute.

Une fois l'exécution du notebook terminée, dans le notebook, vous devriez voir des informations sur le nombre de tests réussis et échoués, ainsi que d'autres détails connexes. Si le cluster n’était pas déjà en cours d’exécution lorsque vous avez start running ce Notebook, le cluster pourrait prendre plusieurs minutes à start up avant d’afficher les résultats.

Votre structure de dépôt devrait maintenant ressembler à ceci :

Text
├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  ├── covid_eda_raw (optional)
│  └── run_unit_tests
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py

Étape 4.4 : vérifier le notebook et les tests associés​

  1. À côté du nom du Notebook, cliquez sur le bouton de la Branch Git first_tests .

  2. Dans la boîte de dialogue best-Notebooks , sur le Changes tab , assurez-vous que les éléments suivants sont sélectionnés :

    • tests/transforms_test.py
    • notebooks/run_unit_tests.py
    • tests/testdata.csv

  3. Pour le message de commit (nécessaire) , saisissez Added tests.

  4. Pour Description (facultatif) , saisissez These are the unit tests for the shared code..

  5. Cliquez sur Commit & Push .

  6. Cliquez sur le Link de la requête d'extraction dans Créer une requête d'extraction sur votre fournisseur Git dans la bannière.

  7. Dans GitHub, créez la pull request, puis fusionnez la pull request dans la branch main.

  8. De retour dans votre Workspace Databricks, fermez la boîte de dialogue best-notebooks si elle est toujours affichée.

Étape 5 : Créer un job pour exécuter les notebooks​

Aux étapes précédentes, vous avez testé votre code partagé manuellement et exécuté vos Notebooks manuellement. Dans cette étape, vous utilisez un Job Databricks pour tester votre code partagé et exécuter automatiquement vos Notebooks, soit à la demande, soit selon un calendrier régulier.

Étape 5.1 : Créer une tâche Job pour exécuter le Notebook de test​

  1. Dans votre Workspace, cliquez Icône Workflows. sur **Tâches et pipelines** dans la barre latérale.

  2. Cliquez sur Créer , puis sur Job .

  3. Modifiez le nom du Job en covid_report.

  4. Cliquez sur la vignette Notebook pour configurer la première tâche. Si la vignette Notebook n'est pas disponible, cliquez sur Ajouter un autre type de tâche et recherchez Notebook .

  5. Pour Nom de la tâche , entrez run_notebook_tests.

  6. Si nécessaire, sélectionnez Notebook dans le menu déroulant Type .

  7. Pour Source , sélectionnez fournisseur Git .

  8. Cliquez sur Ajouter une référence Git .

  9. Dans la boîte de dialogue **Informations Git** :

    1. Pour l'URL du **Git repository**, saisissez l'URL de clonage avec HTTPS de votre GitHub repo. Cet article suppose que votre URL se termine par best-notebooks.git, par exemple https://github.com/<your-GitHub-username>/best-notebooks.git.
    2. Pour le **fournisseur Git**, sélectionnez **GitHub**.
    3. Pour mainla **référence Git (branch / tag / commit)**, saisissez.
    4. À côté de **Référence Git (branch / tag / commit)**, sélectionnez **branch**.
    5. Cliquez sur Confirmer .

  10. Pour Chemin , saisissez notebooks/run_unit_tests. N'ajoutez pas l'extension de fichier .py.

  11. Pour Cluster , sélectionnez le cluster de l'étape précédente.

  12. Cliquez sur **Créer une tâche**.

remarque

Dans ce scénario, Databricks ne recommande pas d'utiliser le bouton de planification dans le notebook, comme décrit dans Créer et gérer des jobs de notebook planifiés, pour planifier un job afin d'exécuter périodiquement ce notebook. En effet, le bouton de planification crée un job en utilisant la dernière copie de travail du notebook dans le référentiel du workspace. Au lieu de cela, Databricks vous recommande de suivre les instructions précédentes pour créer un job qui utilise la dernière version validée du notebook dans le référentiel.

Étape 5.2 : Créez une tâche de Job pour exécuter le Notebook principal.​

  1. Cliquez sur l’icône **+ Ajouter une tâche**.
  2. Un menu contextuel apparaît. Select Notebook .
  3. Pour Nom de la tâche , entrez run_main_notebook.
  4. Pour Type , sélectionnez Notebook .
  5. Pour Chemin , saisissez notebooks/covid_eda_modular. N'ajoutez pas l'extension de fichier .py.
  6. Pour Cluster , sélectionnez le cluster de l'étape précédente.
  7. Vérifier que la valeur de Dépend de est run_notebook-tests.
  8. Cliquez sur **Créer une tâche**.

Étape 5.3 Exécuter le job​

  1. Cliquez sur Exécuter maintenant .

  2. Dans la fenêtre contextuelle, cliquez sur Afficher l'exécution .

  3. Pour voir les résultats du Job, cliquez sur la vignette run_notebook_tests , la vignette run_main_notebook , ou les deux. Les résultats sur chaque vignette sont les mêmes que si vous aviez exécuté les Notebooks vous-même, un par un.

remarque

Ce job s'est exécuté à la demande. Pour configurer ce job afin qu'il s'exécute régulièrement, consultez Automatiser les jobs avec des planifications et des triggers.

(Facultatif) Étape 6 : Configurez le dépôt pour tester le code et exécuter le notebook automatiquement chaque fois que le code change​

À l'étape précédente, vous avez utilisé un Job pour tester automatiquement votre code partagé et exécuter vos Notebooks à un moment donné ou de manière récurrente. Cependant, vous préférerez peut-être Trigger des tests automatiquement lorsque des modifications sont Merge dans votre dépôt GitHub, à l'aide d'un outil de CI/CD tel que GitHub Actions.

Étape 6.1 : Configurer l'accès GitHub à votre workspace​

Dans cette sous-étape, vous configurez un workflow GitHub Actions qui exécute des Jobs dans le Workspace chaque fois que des modifications sont Merge dans votre repository. Pour ce faire, vous donnez à GitHub un jeton Databricks unique pour l'accès.

Pour des raisons de sécurité, Databricks vous déconseille de donner le jeton d'accès personnel de l'utilisateur de votre Databricks Workspace à GitHub. Au lieu de cela, Databricks vous recommande de donner à GitHub un jeton d'accès Databricks associé à un Service Principal Databricks. Pour obtenir des instructions, consultez la section AWS de la page Run Databricks Notebook GitHub Action dans la marketplace GitHub Actions.

important

Les Notebooks sont exécutés avec toutes les autorisations du Workspace de l'identité associée au jeton, c'est pourquoi Databricks recommande d'utiliser un Service Principal. Si vous souhaitez vraiment donner le jeton d'accès personnel de l'utilisateur de votre Workspace Databricks à GitHub à des fins d'exploration personnelle uniquement, et que vous comprenez que pour des raisons de sécurité, Databricks décourage cette pratique, consultez les instructions pour créer le jeton d'accès personnel de l'utilisateur de votre Workspace.

Étape 6.2 : Ajouter le workflow GitHub Actions​

Dans cette sous-étape, vous ajoutez un workflow GitHub Actions pour exécuter le Notebook run_unit_tests chaque fois qu'il y a une demande d'extraction vers le référentiel.

Cette sous-étape stocke le workflow GitHub Actions dans un fichier qui est stocké à plusieurs niveaux de dossiers dans votre dépôt GitHub. GitHub Actions nécessite qu'une hiérarchie de dossiers imbriqués spécifique existe dans votre dépôt afin de fonctionner correctement. Pour effectuer cette étape, vous devez utiliser le site web de votre dépôt GitHub, car l'interface utilisateur des dossiers Git de Databricks ne prend pas en charge la création de hiérarchies de dossiers imbriqués.

  1. Dans le site web de votre dépôt GitHub, cliquez sur la tab Code .

  2. Cliquez sur la flèche à côté de main pour développer la liste déroulante Switch branches or tags .

  3. Dans la boîte Trouver ou créer un Branch , entrez adding_github_actions.

  4. Cliquez sur **Créer une Branch : adding_github_actions depuis 'main'**.

  5. Cliquez sur Ajouter un fichier > Créer un nouveau fichier .

  6. Pour Nommez votre fichier , saisissez .github/workflows/databricks_pull_request_tests.yml.

  7. Dans la fenêtre de l'éditeur, saisissez le code suivant. Ce code utilise le hook pull_request de l'GitHub Actions Run Databricks Notebook pour exécuter le Notebook run_unit_tests.

    Dans le code suivant, remplacez :

    • <your-workspace-instance-URL> avec votre nom d'instance Databricks.
    • <your-access-token> avec le jeton que vous avez généré précédemment.
    • <your-cluster-id> avec votre ID de compute classique cible.
    YAML
    name: Run pre-merge Databricks tests

    on:
      pull_request:

    env:
      # Replace this value with your workspace instance name.
      DATABRICKS_HOST: https://<your-workspace-instance-name>

    jobs:
      unit-test-notebook:
        runs-on: ubuntu-latest
        timeout-minutes: 15

        steps:
          - name: Checkout repo
            uses: actions/checkout@v2
          - name: Run test notebook
            uses: databricks/run-notebook@main
            with:
              databricks-token: <your-access-token>

              local-notebook-path: notebooks/run_unit_tests.py

              existing-cluster-id: <your-cluster-id>

              git-commit: '${{ github.event.pull_request.head.sha }}'

              # Grant all users view permission on the notebook's results, so that they can
              # see the result of the notebook, if they have related access permissions.
              access-control-list-json: >
                [
                  {
                    "group_name": "users",
                    "permission_level": "CAN_VIEW"
                  }
                ]
              run-name: 'EDA transforms helper module unit tests'

  8. Cliquez sur commit modifications .

  9. Dans la boîte de dialogue Commit changes , entrez Create databricks_pull_request_tests.yml dans Message de commit .

  10. Sélectionnez Commit directement dans la branch adding_github_actions et cliquez sur Commit changes .

  11. Dans l'onglet Code , cliquez sur Comparer et requête d'extraction , puis créez la requête d'extraction.

  12. Sur la page de demande de tirage, attendez que l’icône à côté de Exécuter les tests Databricks avant Merge/notebook de tests unitaires (pull_request) affiche une coche verte. (L'icône peut prendre quelques instants à apparaître.) 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**.

  13. Si la coche verte apparaît, fusionnez la requête de tirage dans la Branch main.

(Facultatif) Étape 7 : Mettez à jour le code partagé dans GitHub pour Trigger les tests​

Au cours de cette étape, vous modifiez le code partagé, puis vous intégrez la modification dans votre répertoire GitHub, ce qui déclenche immédiatement les tests automatiquement, en fonction de GitHub Actions de l’étape précédente.

Étape 7.1 : Créer une autre Branch de travail dans le repo​

  1. À partir du navigateur Workspace , ouvrez le dossier Git best-notebooks .
  2. À côté du nom du dossier, cliquez sur le bouton de la Branch Git first_tests .
  3. Dans la boîte de dialogue best-notebooks , cliquez sur la flèche déroulante à côté de la Branch first_tests , et sélectionnez main .
  4. Cliquez sur le bouton **Tirer**. Si vous êtes invité(e) à procéder à l'extraction, cliquez sur **Confirmer**.
  5. Cliquez sur le bouton + ( Créer une Branch ).
  6. Saisissez trigger_tests, puis cliquez sur Créer . (Vous pouvez donner un nom différent à votre Branch.)
  7. Fermez cette boîte de dialogue.

Étape 7.2 : modifier le code partagé​

  1. Depuis le navigateur Workspace , dans le dossier Git best-notebooks , cliquez sur le fichier covid_analysis/transforms.py .

  2. Modifiez la troisième ligne de ce fichier :

    Python
    # Filter by country code.

    Par cela :

    Python
    # Filter by country code. If not specified, use "USA."

Étape 7.3 : Enregistrer la modification pour Trigger les tests​

  1. À côté du nom du fichier, cliquez sur le bouton de la Git **trigger_tests** Branch.
  2. Dans la boîte de dialogue best-Notebooks , dans l'onglet tab , assurez-vous que covid_analysis/transforms.py est sélectionné.
  3. Pour le message de commit (nécessaire) , saisissez Updated comment.
  4. Pour **Description (facultatif)**, saisissez This updates the comment for filter_country.
  5. Cliquez sur Commit & Push .
  6. Cliquez sur le Link de la pull request dans Créer une pull request sur votre fournisseur git dans la bannière, puis créez la pull request dans GitHub.
  7. Sur la page de demande de tirage, attendez que l’icône à côté de Exécuter les tests Databricks avant Merge/notebook de tests unitaires (pull_request) affiche une coche verte. (L'icône peut prendre quelques instants à apparaître.) 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**.
  8. Si la coche verte apparaît, fusionnez la requête de tirage dans la Branch main.
Sur cette page