Partager via

Meilleures pratiques en matière d’ingénierie logicielle pour les notebooks

  • Article

Cet article fournit une procédure pas à pas pratique qui montre comment appliquer les meilleures pratiques en matière d’ingénierie logicielle à vos notebooks Azure Databricks, notamment la gestion de version, le partage de code, les tests, et également l’intégration continue et la livraison ou le déploiement continus (CI/CD).

Lors de cette procédure pas à pas, vous allez :

  • Ajoutez des notebooks à des dossiers Git Azure Databricks pour la gestion de version.
  • Extrayez des parties du code de l’un des notebooks dans un module partageable.
  • Testez le code partagé.
  • Exécutez les notebooks à partir d’un travail Azure Databricks.
  • Si vous le souhaitez, appliquez l’intégration et le déploiement continus au code partagé.

Spécifications

Pour effectuer cette procédure pas à pas, vous devez fournir les ressources suivantes :

  • Un dépôt distant avec un fournisseur Git pris en charge par Databricks. La procédure pas à pas de cet article utilise GitHub. Cette procédure pas à pas suppose que vous disposez d’un référentiel GitHub nommé best-notebooks disponible. (Vous pouvez attribuer un autre nom à votre référentiel. Si vous le faites, remplacez best-notebooks par le nom de votre référentiel 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.

    Notes

    Si vous créez un nouveau référentiel, veillez à initialiser le référentiel avec au moins un fichier, par exemple un fichier README.

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

  • Un cluster à usage général Azure Databricks dans l’espace de travail. Pour exécuter des notebooks pendant la phase de conception, vous devez attacher les notebooks à un cluster à usage général en cours d’exécution. Plus loin, cette procédure pas à pas utilise une tâche Azure Databricks pour automatiser l’exécution des notebooks sur ce cluster. (Vous pouvez également exécuter des travaux sur des clusters de travail qui existent uniquement pour les durées de vie des travaux.) Créez un cluster à usage général si vous n’en avez pas déjà un.

Étape 1 : Configurer les dossiers Git Databricks

Lors de cette étape, vous allez connecter votre dépôt GitHub existant aux dossiers Git Azure Databricks dans votre espace de travail Azure Databricks existant.

Pour permettre à votre espace de travail de se connecter à votre référentiel GitHub, vous devez d’abord fournir vos informations d’identification GitHub à votre espace de travail, si vous ne l’avez pas déjà fait.

Étape 1.1 : Fournir vos informations d’identification GitHub

  1. Cliquez sur votre nom d’utilisateur en haut à droite dans l’espace de travail, puis 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 le nom d’utilisateur ou l’e-mail du fournisseur Git, entrez votre nom d’utilisateur GitHub.
  6. Pour Jeton, entrez votre jeton d’accès personnel GitHub (classique). Ce jeton d’accès personnel (classique) doit disposer des autorisations de dépôt et de workflow.
  7. Cliquez sur Enregistrer.

Étape 1.2 : Se connecter à votre référentiel GitHub

  1. Dans la barre latérale de l’espace de travail, cliquez sur Espace de travail.
  2. Dans le navigateur Espace de travail, développez Espace de travail > Utilisateurs.
  3. Cliquez avec le bouton droit sur le dossier de votre nom 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 référentiel Git, entrez l’URL Cloner avec HTTPS GitHub de votre référentiel GitHub. 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 Fournisseur Git, sélectionnez GitHub.
    3. Laissez le Nom du dossier Git défini sur le nom de votre dépôt, par exemple best-notebooks.
    4. Cliquez sur Créer un dossier Git.

Étape 2 : Importer et exécuter le notebook

Dans cette étape, vous importez un notebook externe existant dans votre référentiel. Vous pouvez créer vos propres notebooks pour cette procédure pas à pas, mais pour accélérer les choses, nous vous en fournissons ici.

Étape 2.1 : Créer une branche de travail dans le référentiel

Dans cette sous-étape, vous créez une branche nommée eda dans votre référentiel. Cette branche vous permet de travailler sur des fichiers et du code indépendamment de la branche main de votre référentiel, ce qui constitue une bonne pratique d’ingénierie logicielle. (Vous pouvez donner un autre nom à votre branche.)

Notes

Dans certains référentiels, la mainbranche peut être nomméemaster à la place. Si c’est le cas, remplacez main par master tout au long de cette procédure pas à pas.

Conseil

Si vous n’êtes pas familiarisé avec l’utilisation des branches Git, consultez Branches Git - Branches dans un nutshell sur le site web Git.

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

  2. En regard du nom du dossier sous la barre de navigation de l’espace de travail, cliquez sur le bouton de la branche Git main.

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

    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 procédure pas à pas.

  4. Entrez eda et cliquez sur Créer.

  5. Fermer cette boîte de dialogue.

Étape 2.2 : Importer le notebook dans le référentiel

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

  • Copie un fichier CSV à partir du référentiel GitHub owid/covid-19-data sur un cluster dans votre espace de travail. Ce fichier CSV contient des données publiques sur les hospitalisations COVID-19 et les mesures de soins intensifs provenant du monde entier.
  • Lit le contenu du fichier CSV dans un DataFrame pandas.
  • Filtre les données pour contenir des métriques provenant uniquement des États-Unis.
  • Affiche un tracé des données.
  • Enregistre le DataFrame pandas en tant que DataFrame API Pandas sur Spark.
  • Effectue le nettoyage des données sur le DataFrame API Pandas sur Spark.
  • Écrit le DataFrame API Pandas sur Spark en tant que table Delta dans votre espace de travail.
  • Affiche le contenu de la table Delta.

Bien que vous puissiez créer ici votre propre notebook dans votre dépôt, l’importation d’un notebook existant permet d’accélérer cette procédure pas à pas. Pour créer un notebook dans cette branche ou y déplacer un notebook existant, au lieu d’importer un notebook, consultez Utilisation de base des fichiers d’espace de travail.

  1. Dans le dossier Git best-notebooks, cliquez sur Créer > Dossier.
  2. Dans la boîte de dialogue Nouveau dossier, entrez notebooks, puis cliquez sur Créer.
  3. Dans le dossier notebooks, cliquez sur le kebab, puis sur Importer.
  4. Dans la boîte de dialogue Importer :

    1. Pour Importer à partir de, sélectionnez l’URL.

    2. Entrez l’URL du contenu brut du notebook covid_eda_raw dans le référentiel databricks/notebook-best-practices dans GitHub. Pour obtenir cette URL : i. Atteindre https://github.com/databricks/notebook-best-practices. ii. Cliquez sur le dossier notebooks. iii. Cliquez sur le fichier covid_eda_raw.py. iv. Cliquez sur Brut. v. Copiez l’URL complète à partir de la barre d’adresse de votre navigateur web et collez-la dans la boîte de dialogue Importer.

      Remarque

      La boîte de dialogue Importer fonctionne uniquement avec les URL Git pour les dépôts publics.

    3. Cliquez sur Importer.

Étape 2.3 : Exécuter le notebook

  1. Si le notebook n’est pas affiché, ouvrez le dossier notebooks, puis cliquez sur le notebook covid_eda_raw dans le dossier.
  2. Sélectionnez le cluster auquel attacher ce notebook. Pour obtenir des instructions sur la création d’un cluster, consultez Créer un cluster.
  3. Cliquez sur Exécuter tout.
  4. Attendez que le notebook s’exécute.

Une fois l’exécution du notebook terminée, vous devez voir dans le notebook un tracé 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 commencé à exécuter ce notebook, le démarrage du cluster peut prendre plusieurs minutes avant d’afficher les résultats.

Étape 2.4 : Vérifier et fusionner le notebook

Dans cette sous-étape, vous enregistrez votre travail jusqu’à présent dans votre référentiel GitHub. Vous fusionnez ensuite le notebook de votre branche de travail dans la branche de main votre référentiel.

  1. En regard du nom du notebook, cliquez sur le bouton de la branche Git eda.
  2. Dans la boîte de dialogue best-notebooks, sous l’onglet Modifications, vérifiez que le fichier notebooks/covid_eda_raw.py est sélectionné.
  3. Pour Message de validation (obligatoire), entrez Added raw notebook.
  4. Pour Description (facultatif), entrez This is the first version of the notebook..
  5. Cliquez sur Commiter et pousser.
  6. Cliquez sur le lien de demande de tirage dans Créer une demande de tirage sur votre fournisseur Git dans la bannière.
  7. Dans GitHub, créez la demande de tirage, puis fusionnez-la dans la branche main.
  8. De retour dans votre espace de travail Azure Databricks, fermez la boîte de dialogue best-notebooks si elle est toujours affichée.

Étape 3 : Déplacer du code dans un module partagé

Dans cette étape, vous déplacez une partie du code dans votre notebook vers un ensemble de fonctions partagées en dehors de votre notebook. Cette opération vous permet d’utiliser ces fonctions avec d’autres notebooks similaires, ce qui peut accélérer le codage futur et vous aider à 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 meilleure pratique d’ingénierie logicielle, peut augmenter la qualité globale de votre code au fur et à mesure de l’utilisation.

Étape 3.1 : Créer une autre branche de travail dans le référentiel

  1. En regard du nom du notebook, cliquez sur le bouton de la branche Git eda.
  2. Dans la boîte de dialogue best-notebooks, cliquez sur la flèche déroulante en regard de la branche eda, puis sélectionnez main.
  3. Cliquez sur le bouton Tirer. Si vous êtes invité à procéder au tirage, cliquez sur Confirmer.
  4. Cliquez sur le bouton Créer une branche.
  5. Entrez first_modules, puis cliquez sur Créer. (Vous pouvez donner un autre nom à votre branche.)
  6. Fermer cette boîte de dialogue.

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

Pour accélérer cette procédure pas à pas, dans cette sous-étape, vous importez un autre notebook existant dans votre référentiel. Ce notebook fait les mêmes choses que le notebook précédent, à l’exception que ce notebook appelle les fonctions de code partagées stockées en dehors du notebook. Là encore, vous pouvez créer votre propre notebook dans votre référentiel et effectuer le partage de code réel vous-même.

  1. Dans le navigateur Espace de travail, cliquez avec le bouton droit sur le dossier notebooks, puis cliquez sur Importer.
  2. Dans la boîte de dialogue Importer :

    1. Pour Importer à partir de, sélectionnez l’URL.

    2. Entrez l’URL du contenu brut du notebook covid_eda_modular dans le référentiel databricks/notebook-best-practices dans GitHub. Pour obtenir cette URL : i. Atteindre https://github.com/databricks/notebook-best-practices. ii. Cliquez sur le dossier notebooks. iii. Cliquez sur le fichier covid_eda_modular.py. iv. Cliquez sur Brut. v. Copiez l’URL complète à partir de la barre d’adresse de votre navigateur web dans la boîte de dialogue Importer des notebooks.

      Notes

      La boîte de dialogue Importer des notebooks fonctionne uniquement avec les URL Git pour les référentiels publics.

    3. Cliquez sur Importer.

Étape 3.3 : Ajouter les fonctions de code partagées prises en charge du notebook

  1. Dans le navigateur Espace de travail, 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, entrez covid_analysis, puis cliquez sur Créer.

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

  4. Dans la boîte de dialogue Nom du nouveau fichier, entrez transforms.py, puis cliquez sur Créer un fichier.

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

    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

Conseil

Pour d’autres techniques de partage de code, consultez Partager du code entre des notebooks Databricks.

Étape 3.4 : Ajouter les dépendances du code partagé

Le code précédent possède plusieurs dépendances de package Python pour permettre au code de s’exécuter correctement. Dans cette sous-étape, vous déclarez ces dépendances de package. La déclaration de dépendances améliore la reproductibilité en utilisant des versions de bibliothèques définies avec précision.

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

    Remarque

    Le fichier contenant la liste des dépendances de package doit aller à la racine du dossier Git, et non dans le dossier notebooks ou covid_analysis.

  2. Dans la boîte de dialogue Nom du nouveau fichier, entrez requirements.txt, puis cliquez sur Créer un fichier.

  3. Dans la fenêtre de l’éditeur requirements.txt, entrez le code suivant.

    Remarque

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

    -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

    Notes

    Le fichier précédent répertorie des versions de package spécifiques. Pour une meilleure compatibilité, vous pouvez référencer ces versions avec celles installées sur votre cluster à usage général. 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.

La structure de votre référentiel doit maintenant se présenter comme suit :

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

Étape 3.5 : Exécuter 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. Dans le navigateur Espace de travail, cliquez sur le notebook covid_eda_modular dans le dossier notebooks.
  2. Sélectionnez le cluster auquel attacher ce notebook.
  3. Cliquez sur Exécuter tout.
  4. Attendez que le notebook s’exécute.

Une fois l’exécution du notebook terminée, vous devez y voir les mêmes résultats que pour le 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 bloc-notes est qu’un filtre différent est utilisé (un iso_code de DZA la place de USA). Si le cluster n’était pas déjà en cours d’exécution lorsque vous avez commencé à exécuter ce notebook, le démarrage du cluster peut prendre plusieurs minutes avant d’afficher les résultats.

  1. En regard du nom du notebook, cliquez sur le bouton de la branche Git first_modules.
  2. Dans la boîte de dialogue best-notebooks, sous l’onglet Modifications, vérifiez que les éléments suivants sont sélectionnés :
    • requirements.txt
    • covid_analysis/transforms.py
    • notebooks/covid_eda_modular.py
  3. Pour Message de validation (obligatoire), entrez Added refactored notebook.
  4. Pour Description (facultatif), entrez This is the second version of the notebook..
  5. Cliquez sur Commiter et pousser.
  6. Cliquez sur le lien de demande de tirage dans Créer une demande de tirage sur votre fournisseur Git dans la bannière.
  7. Dans GitHub, créez la demande de tirage, puis fusionnez-la dans la branche main.
  8. De retour dans votre espace de travail Azure Databricks, fermez la boîte de dialogue best-notebooks si elle est toujours affichée.

Étape 4 : Tester le code partagé

Dans cette étape, vous testez le code partagé de la dernière étape. Toutefois, vous devez tester ce code sans exécuter le notebook covid_eda_modular. En effet, si le code partagé ne parvient pas à s’exécuter, le notebook lui-même échouera probablement également. Vous devez d’abord identifier les échecs dans votre code partagé afin que votre notebook principal n’échoue pas ultérieurement. Cette technique de test est une bonne pratique d’ingénierie logicielle.

Conseil

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

Étape 4.1 : Créer une autre branche de travail dans le référentiel

  1. En regard du nom du notebook, cliquez sur le bouton de la branche Git first_modules.
  2. Dans la boîte de dialogue best-notebooks, cliquez sur la flèche déroulante en regard de la branche first_modules, puis sélectionnez main.
  3. Cliquez sur le bouton Tirer. Si vous êtes invité à procéder au tirage, cliquez sur Confirmer.
  4. Cliquez sur Créer une branche.
  5. Entrez first_tests, puis cliquez sur Créer. (Vous pouvez donner un autre nom à votre branche.)
  6. Fermer cette boîte de dialogue.

Étape 4.2 : Ajouter les tests

Dans cette sous-étape, vous utilisez l’infrastructure pytest pour tester votre code partagé. Dans ces tests, vous déclarez si des résultats de test particuliers sont atteints. Si un test produit un résultat inattendu, l’assertion de ce test particulier échoue, et par conséquent le test lui-même échoue.

  1. Dans le navigateur Espace de travail, cliquez avec le bouton droit sur votre dossier Git, puis cliquez sur Créer > Dossier.

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

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

  4. Dans la boîte de dialogue Nom du nouveau fichier, entrez testdata.csv, puis cliquez sur Créer un fichier.

  5. Dans la fenêtre de l’éditeur testdata.csv, entrez 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 Nom du nouveau fichier, entrez transforms_test.py, puis cliquez sur Créer un fichier.

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

    # 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()

La structure de votre référentiel doit maintenant se présenter comme suit :

├── 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 procédure pas à pas, vous utilisez dans cette sous-étape un notebook importé pour exécuter les tests précédents. Ce notebook télécharge et installe les packages Python dépendants des tests dans votre espace de travail, exécute les tests et rapporte les résultats des tests. Bien que vous puissiez exécuter pytest à partir du terminal web de votre cluster, l’exécuter pytest à partir d’un notebook peut être plus pratique.

Notes

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

  1. Dans le navigateur Espace de travail, 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 à partir de, sélectionnez l’URL.

    2. Entrez l’URL du contenu brut du notebook run_unit_tests dans le référentiel databricks/notebook-best-practices dans GitHub. Pour obtenir cette URL : i. Atteindre https://github.com/databricks/notebook-best-practices. ii. Cliquez sur le dossier notebooks. iii. Cliquez sur le fichier run_unit_tests.py. iv. Cliquez sur Brut. v. Copiez l’URL complète à partir de la barre d’adresse de votre navigateur web dans la boîte de dialogue Importer des notebooks.

      Notes

      La boîte de dialogue Importer des notebooks fonctionne uniquement avec les URL Git pour les référentiels publics.

    3. Cliquez sur Importer.

  3. Sélectionnez le cluster auquel attacher ce notebook.
  4. Cliquez sur Exécuter tout.
  5. Attendez que le notebook s’exécute.

Une fois le notebook en cours d’exécution, vous devriez voir dans le notebook des informations sur le nombre de tests réussis et ayant échoué, ainsi que d’autres détails complémentaires. Si le cluster n’était pas déjà en cours d’exécution lorsque vous avez commencé à exécuter ce notebook, le démarrage du cluster peut prendre plusieurs minutes avant d’afficher les résultats.

La structure de votre référentiel doit maintenant se présenter comme suit :

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  ├── covid_eda_raw (optional)
│  └── run_unit_tests
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py
  1. En regard du nom du notebook, cliquez sur le bouton de la branche Git first_tests.
  2. Dans la boîte de dialogue best-notebooks, sous l’onglet Modifications, vérifiez que les éléments suivants sont sélectionnés :
    • tests/transforms_test.py
    • notebooks/run_unit_tests.py
    • tests/testdata.csv
  3. Pour Message de validation (obligatoire), entrez Added tests.
  4. Pour Description (facultatif), entrez These are the unit tests for the shared code..
  5. Cliquez sur Commiter et pousser.
  6. Cliquez sur le lien de demande de tirage dans Créer une demande de tirage sur votre fournisseur Git dans la bannière.
  7. Dans GitHub, créez la demande de tirage, puis fusionnez-la dans la branche main.
  8. De retour dans votre espace de travail Azure Databricks, fermez la boîte de dialogue best-notebooks si elle est toujours affichée.

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

Dans les étapes précédentes, vous avez testé votre code partagé et exécuté vos notebooks manuellement. Dans cette étape, vous allez utiliser un travail Azure Databricks pour tester votre code partagé et exécuter vos notebooks automatiquement, à la demande ou selon une planification régulière.

Étape 5.1 : Créer une tâche de travail pour exécuter le notebook de test

  1. Dans la barre latérale de l’espace de travail, cliquez sur Workflows.
  2. Sous l’onglet Travaux, cliquez sur Créer un travail.
  3. Nommez le travail covid_report.
  4. Pour Nom du travail, entrez run_notebook_tests.
  5. Pour Type, sélectionnez Notebook.
  6. Pour Source, sélectionnez Fournisseur Git.
  7. Cliquez sur Ajouter une référence Git.
  8. Dans la boîte de dialogue Informations Git :
    1. Pour l’URL du référentiel Git, entrez l’URL Cloner avec HTTPS GitHub de votre référentiel GitHub. 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 Fournisseur Git, sélectionnez GitHub.
    3. Pour Référence Git (branche / balise / commit), entrez main.
    4. En regard de Référence Git (branche / balise / commit), sélectionnez branche.
    5. Cliquez sur Confirmer.
  9. Pour Chemin d’accès, entrez notebooks/run_unit_tests. N’ajoutez pas l’extension de fichier .py.
  10. Pour Cluster, sélectionnez le cluster de l’étape précédente.
  11. Cliquez sur Create task.

Remarque

Dans ce scénario, Databricks ne vous recommande pas d’utiliser le bouton de planification dans le notebook, comme décrit dans Créer et gérer des tâches de notebook planifiées, pour planifier un travail afin d’exécuter régulièrement ce notebook. Cela est dû au fait que le bouton de planification crée un travail à l’aide de la dernière copie de travail du notebook dans le référentiel de l’espace de travail. Au lieu de cela, Databricks vous recommande de suivre les instructions précédentes pour créer un travail qui utilise la dernière version validée du notebook dans le référentiel.

Étape 5.2 : Créer une tâche de travail pour exécuter le notebook principal

  1. Cliquez sur l’icône + Ajouter une tâche.
  2. Un menu contextuel s’affiche. Sélectionnez Notebook.
  3. Pour Nom du travail, entrez run_main_notebook.
  4. Pour Type, sélectionnez Notebook.
  5. Pour Chemin d’accès, entrez 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érifiez que la valeur Dépend de est run_notebook-tests.
  8. Cliquez sur Create task.

Étape 5.3 Exécuter le travail

  1. Cliquez sur Exécuter maintenant.

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

    Notes

    Si la fenêtre contextuelle disparaît trop rapidement, procédez comme suit :

    1. Dans la barre latérale de l’environnement Data Science & Engineering ou Databricks Mosaic AI, cliquez sur Flux de travail.
    2. Sous l’onglet Exécutions des travaux, cliquez sur la valeur Heure de début du travail le plus récent avec covid_report dans la colonne Travaux.

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

Notes

Ce travail s’est exécuté à la demande. Pour configurer ce travail de façon régulière, consultez Types de déclencheurs pour les travaux Databricks.

(Facultatif) Étape 6 : Configurer le référentiel pour tester le code et exécuter automatiquement le notebook chaque fois que le code change

À l’étape précédente, vous avez utilisé un travail pour tester votre code partagé et exécuter vos notebooks automatiquement à un moment donné ou de façon récurrente. Toutefois, vous préférez peut-être déclencher automatiquement des tests lorsque des modifications sont fusionnées dans votre dépôt GitHub, à l’aide d’un outil CI/CD tel que GitHub Actions.

Étape 6.1 : Configurer l’accès GitHub à votre espace de travail

Lors de cette sous-étape, vous configurez un workflow GitHub Actions qui exécute des travaux dans l’espace de travail chaque fois que des modifications sont fusionnées dans votre dépôt. Pour ce faire, vous donnez à GitHub un jeton Azure Databricks unique pour autoriser 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 espace de travail Azure Databricks à GitHub. À la place, Databricks recommande de donner à GitHub un jeton Microsoft Entra ID associé à un principal de service Microsoft Entra ID. Pour obtenir des instructions, consultez la section Azure de la page Exécuter le notebook Databricks GitHub Action dans la Place de marché GitHub Actions.

Important

Les notebooks sont exécutés avec toutes les autorisations d’espace de travail de l’identité associée au jeton. Databricks recommande donc d’utiliser un principal de service. Si vous souhaitez vraiment donner le jeton d’accès personnel de l’utilisateur de votre espace de travail Azure Databricks à GitHub uniquement à des fins d’exploration personnelle 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 espace de travail.

Étape 6.2 : Ajouter le flux de travail GitHub Actions

Dans cette sous-étape, vous ajoutez un flux de travail GitHub Actions pour exécuter le notebook run_unit_tests chaque fois qu’une demande de tirage est envoyée au référentiel.

Cette sous-étape stocke le flux de travail GitHub Actions dans un fichier stocké dans plusieurs niveaux de dossier dans votre référentiel GitHub. GitHub Actions nécessite une hiérarchie de dossiers imbriqués spécifique dans votre référentiel 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 Azure Databricks ne prend pas en charge la création de hiérarchies de dossiers imbriqués.

  1. Dans le site web de votre référentiel GitHub, cliquez sur l’onglet Code.

  2. Cliquez sur la flèche en regard de main pour développer la liste déroulante Changer de branches ou d’étiquettes.

  3. Dans la zone Rechercher ou créer une branche, entrez adding_github_actions.

  4. Cliquez sur Créer une branche : adding_github_actions à partir de « main ».

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

  6. Pour Nommer votre fichier, entrez .github/workflows/databricks_pull_request_tests.yml.

  7. Dans la fenêtre de l’éditeur, entrez le code suivant. Ce code utilise le hook pull_request à partir de l’action GitHub Exécuter le notebook Databricks pour exécuter le notebook run_unit_tests.

    Dans le code suivant, remplacez :

    • <your-workspace-instance-URL> avec votre nom d’instance Azure Databricks.
    • <your-access-token> avec le jeton que vous avez généré précédemment.
    • <your-cluster-id> avec votre ID de cluster cible.
    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 Valider les changements.

  9. Dans la boîte de dialogue Valider les modifications, entrez Create databricks_pull_request_tests.yml dans Message de validation.

  10. Sélectionnez Commiter directement sur la branche adding_github_actions et cliquez sur Valider les modifications.

  11. Sous l’onglet Code , cliquez sur comparer la demande de tirage, puis créez la demande de tirage.

  12. Dans la page de demande de tirage, attendez que l’icône en regard de Exécuter des tests Databricks pré-fusion / unit-test-notebook (pull_request) affiche une coche verte. (Cela peut prendre quelques instants 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 ne s’apparaissent plus, cliquez sur Afficher toutes les vérifications.

  13. Si la coche verte s’affiche, fusionnez la demande de tirage dans la branche main.

(Facultatif) Étape 7 : Mettre à jour le code partagé dans GitHub pour déclencher des tests

Lors de cette étape, vous apportez une modification au code partagé, puis vous envoyez la modification dans votre dépôt GitHub, ce qui déclenche immédiatement les tests automatiquement, en fonction de l’action GitHub de l’étape précédente.

Étape 7.1 : Créer une autre branche de travail dans le référentiel

  1. Dans le navigateur Espace de travail, ouvrez le dossier Git best-notebooks.
  2. En regard du nom du dossier, cliquez sur le bouton de la branche Git first_tests.
  3. Dans la boîte de dialogue best-notebooks, cliquez sur la flèche déroulante en regard de la branche first_tests, puis sélectionnez main.
  4. Cliquez sur le bouton Tirer. Si vous êtes invité à procéder au tirage, cliquez sur Confirmer.
  5. Cliquez sur le bouton + (Créer une branche).
  6. Entrez trigger_tests, puis cliquez sur Créer. (Vous pouvez donner un autre nom à votre branche.)
  7. Fermer cette boîte de dialogue.

Étape 7.2 : Modifier le code partagé

  1. Dans le navigateur Espace de travail, dans le dossier Git best-notebooks, cliquez sur le fichier covid_analysis/transforms.py.

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

    # Filter by country code.

    Par ceci :

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

Étape 7.3 : Archiver la modification pour déclencher les tests

  1. En regard du nom du fichier, cliquez sur le bouton de la branche Git trigger_tests.
  2. Dans la boîte de dialogue best-notebooks, sous l’onglet Modifications, vérifiez que covid_analysis/transforms.py est sélectionné.
  3. Pour Message de validation (obligatoire), entrez Updated comment.
  4. Pour Description (facultatif), entrez This updates the comment for filter_country..
  5. Cliquez sur Commiter et pousser.
  6. Cliquez sur le lien de demande de tirage dans Créer une demande de tirage sur votre fournisseur Git dans la bannière, puis créez la demande de tirage dans GitHub.
  7. Dans la page de demande de tirage, attendez que l’icône en regard de Exécuter des tests Databricks pré-fusion / unit-test-notebook (pull_request) affiche une coche verte. (Cela peut prendre quelques instants 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 ne s’apparaissent plus, cliquez sur Afficher toutes les vérifications.
  8. Si la coche verte s’affiche, fusionnez la demande de tirage dans la branche main.