Condividi tramite

Procedure consigliate di ingegneria del software per i notebook

  • Articolo

Questo articolo fornisce un'esercitazione pratica che dimostra come applicare le procedure consigliate di ingegneria del software ai notebook di Azure Databricks, tra cui controllo della versione, condivisione del codice, test e, a scelta, integrazione continua e recapito continuo o distribuzione (CI/CD).

Questa procedura dettagliata è costituita dai passaggi seguenti:

  • Aggiungere notebook alle cartelle Git di Azure Databricks per il controllo della versione.
  • Estrarre parti di codice da uno dei notebook in un modulo condivisibile.
  • Testare il codice condiviso.
  • Eseguire i notebook da un processo di Azure Databricks.
  • Facoltativamente, applicare CI/CD al codice condiviso.

Requisiti

Per completare la procedura dettagliata è necessario fornire le risorse seguenti:

  • Un repository remoto con un provider Git supportato da Databricks. La procedura dettagliata di questo articolo usa GitHub. Questa procedura dettagliata presuppone che sia disponibile un repository GitHub denominato best-notebooks. È possibile assegnare al repository un nome diverso. In questo caso, sostituire best-notebooks con il nome del repository di questa procedura dettagliata. Creare un repository GitHub se non ne è già disponibile uno.

    Nota

    Se si crea un nuovo repository, assicurarsi di inizializzare il repository con almeno un file, ad esempio un file README.

  • Un'area di lavoro di Azure Databricks. Creare un'area di lavoro se non ne esiste già una.

  • Un cluster multifunzionale di Azure Databricks nell'area di lavoro. Per eseguire notebook durante la fase di progettazione, collegare i notebook a un cluster multifunzionale in esecuzione. Più avanti, questa procedura dettagliata usa un processo di Azure Databricks per automatizzare l'esecuzione dei notebook in questo cluster. È anche possibile eseguire processi nei cluster di processi esistenti solo per la durata dei processi. Creare un cluster multifunzionale se non ne è già disponibile uno.

Passaggio 1: Set cartelle Git di Databricks

In questo passaggio si connette il repository GitHub esistente alle cartelle Git di Azure Databricks nell'area di lavoro di Azure Databricks esistente.

Per consentire all'area di lavoro di connettersi al repository GitHub, è necessario prima fornire all'area di lavoro il token GitHub credentials, se non è già stato fatto.

Passaggio 1.1: Fornire il tuo GitHub credentials

  1. Fare clic sul nome utente nell'angolo in alto a destra dell'area di lavoro e quindi fare clic su Impostazioni nel menu a tendina list.
  2. Nella barra laterale Impostazioni, in Utente, cliccare Account collegati.
  3. In integrazione Git, per provider Git, selectGitHub.
  4. Cliccare Token di accesso personale.
  5. In Nome utente o indirizzo e-mail del provider Git immettere il proprio nome utente di GitHub.
  6. Per Token immettere il proprio token di accesso personale di GitHub (versione classica). Questo token di accesso personale (versione classica) deve avere le autorizzazioni per il repository e per il flusso di lavoro.
  7. Cliccare Salva.

Passaggio 1.2: Connettersi al repository GitHub

  1. Nella barra laterale dell'area di lavoro, cliccare Area di lavoro.
  2. Nel browser Area di lavoro espandere Area di lavoro > Utenti.
  3. Fare clic con il pulsante destro del mouse sulla cartella del proprio nome utente, quindi scegliere Crea > Cartella Git.
  4. Nella finestra di dialogo Crea cartella Git:
    1. Per URL repository Git immettere l'URL Clone with HTTPS (Clona con HTTPS) di GitHub del proprio repository GitHub. Questo articolo presuppone che l'URL termini con best-notebooks.git, ad esempio https://github.com/<your-GitHub-username>/best-notebooks.git.
    2. Per provider Git, selectGitHub.
    3. Lascia il nome della cartella Gitset come il nome del tuo repository, per esempio best-notebooks.
    4. Cliccare Crea cartella Git.

Passaggio 2: Importare ed eseguire il notebook

In questo passaggio si importa nel repository un notebook esterno esistente. È possibile creare notebook personalizzati per questa procedura dettagliata, ma per velocizzare le operazioni forniremo notebook già pronti.

Passaggio 2.1: Creare un ramo di lavoro nel repository

In questo passaggio secondario si crea un ramo denominato eda nel repository. Questo ramo consente di lavorare su file e codice indipendentemente dal ramo main del repository, seguendo una procedura consigliata per l'ingegneria del software. (È possibile assegnare al ramo un nome diverso.)

Nota

In alcuni repository, il ramo main può essere invece denominato master. In questo caso, sostituire main con master in questa procedura dettagliata.

Suggerimento

Se non si ha familiarità con l'uso dei rami Git, vedere Git Branches - Branches in a Nutshell (Rami Git - Breve panoramica sui rami) nel sito Web Git.

  1. La cartella Git del passaggio 1.2 deve essere aperta. In caso contrario, nella barra laterale Area di lavoro espandere Area di lavoro > Utenti, quindi espandere la cartella del proprio nome utente e cliccare la propria cartella Git.

  2. Accanto al nome della cartella sotto il percorso di navigazione dell'area di lavoro, cliccare il pulsante del ramo Git principale.

  3. Nella finestra di dialogo best-notebooks cliccare il pulsante Crea ramo.

    Nota

    Se il repository ha un nome diverso da best-notebooks, il titolo di questa finestra di dialogo sarà diverso, qui e in questa procedura dettagliata.

  4. Immettere eda e cliccare Crea.

  5. Chiudere questa finestra di dialogo.

Passaggio 2.2: Importare il notebook nel repository

In questo passaggio secondario si importa nel proprio repository un notebook esistente da un altro repository. Questo notebook esegue le operazioni seguenti:

  • Copia un file CSV dal repository GitHub owid/covid-19-data in un cluster dell'area di lavoro. Questo file CSV contiene dati pubblici sulle ospedalizzazioni COVID-19 e sulle metriche di terapia intensiva di tutto il mondo.
  • Legge il contenuto del file CSV in un DataFramepandas.
  • Filtra i dati in modo che contengano metriche solo dagli Stati Uniti.
  • Visualizza un tracciato dei dati.
  • Salva il DataFrame pandas come un DataFramePandas API on Spark.
  • Esegue la pulizia dei dati nell'API Pandas nel DataFrame Spark.
  • Scrive l'API di Pandas nel DataFrame di Spark come Delta table nell'area di lavoro.
  • Visualizza i contenuti del Delta table.

Anche se è possibile creare un notebook personalizzato nel repository, l'importazione di un notebook esistente consente di velocizzare questa procedura dettagliata. Per creare un notebook in questo ramo o spostare un notebook esistente in questo ramo anziché importare un notebook, vedere Utilizzo di base dei file dell'area di lavoro.

  1. Nella cartella Git best-notebooks, cliccare Crea > Cartella.
  2. Nella finestra di dialogo Nuova cartella immettere notebooks, quindi cliccare Crea.
  3. Nella cartella notebooks cliccare il menu kebab e quindi su Importa.
  4. Nella finestra di dialogo Importa:

    1. Per l'importazione dadi , URL.

    2. Immettere l'URL del contenuto non elaborato del notebook covid_eda_raw nel repository databricks/notebook-best-practices in GitHub. Per get questo URL: i. Andare a https://github.com/databricks/notebook-best-practices. ii. Cliccare la cartella notebooks. iii. Cliccare il file covid_eda_raw.py. iv. Cliccare Raw (Non elaborato). v. Copiare l'URL completo dalla barra degli indirizzi del Web browser nella finestra di dialogo Importa.

      Nota

      La finestra di dialogo Importa funziona con gli URL Git solo per i repository pubblici.

    3. Cliccare Importa.

Passaggio 2.3: Eseguire il notebook

  1. Se il notebook non è già visualizzato, aprire la cartella notebook, quindi cliccare il notebook covid_eda_raw all'interno della cartella.
  2. Select il cluster per collegare questo notebook a. Per altre informazioni sulla creazione di un cluster, vedere Creare un cluster.
  3. Cliccare Esegui tutto.
  4. Attendere l'esecuzione del notebook.

Al termine dell'esecuzione del notebook, nel notebook dovrebbe essere visualizzato un grafico dei dati e oltre 600 righe di dati grezzi nella sezione Delta table. Se il cluster non era già in esecuzione quando si è iniziato a eseguire questo notebook, potrebbero essere necessari alcuni minuti per l'avvio del cluster prima della visualizzazione dei risultati.

Passaggio 2.4: Eseguire il check-in del notebook e unire il notebook

In questa procedura secondaria si salva il lavoro completato fino a questo momento nel repository GitHub. Si unisce quindi il notebook dal ramo di lavoro al ramo main del repository.

  1. Accanto al nome del notebook, cliccare il pulsante del ramo Git eda.
  2. Nella finestra di dialogo best-notebooks, nella scheda Modifiche, assicurarsi che sia selezionato il file notebooks/covid_eda_raw.py.
  3. Per Messaggio di commit (obbligatorio), immettere Added raw notebook.
  4. Per Descrizione (facoltativa), immettere This is the first version of the notebook.
  5. Cliccare Commit e push.
  6. Cliccare il collegamento della richiesta pull in Creare una richiesta pull nel proprio provider Git nel banner.
  7. In GitHub, creare la richiesta pull e unire la richiesta pull nel ramo main.
  8. Tornare all'area di lavoro di Azure Databricks e chiudere la finestra di dialogo best-notebooks se ancora visualizzata.

Passaggio 3: Spostare il codice in un modulo condiviso

In questo passaggio, si sposta parte del codice dal notebook in una sezione set di funzioni condivise al di fuori del notebook. In questo modo è possibile usare queste funzioni con altri notebook simili, velocizzando la programmazione futura e garantendo risultati del notebook più prevedibili e coerenti. La condivisione di questo codice consente anche di testare più facilmente queste funzioni, che come procedura consigliata per l'ingegneria del software può aumentare la qualità complessiva del codice man mano che si procede.

Passaggio 3.1: Creare un altro ramo di lavoro nel repository

  1. Accanto al nome del notebook, cliccare il pulsante del ramo Git eda.
  2. Nella finestra di dialogo best-notebooks fare clic sulla freccia a discesa accanto al ramo eda e select_principale_.
  3. Cliccare il pulsante Pull. Se viene richiesto di procedere con il pull, cliccare Confirm (Conferma).
  4. Cliccare il pulsante Crea ramo.
  5. Immettere first_modules e cliccare Create (Crea). (È possibile assegnare al ramo un nome diverso.)
  6. Chiudere questa finestra di dialogo.

Passaggio 3.2: Importare il notebook nel repository

Per velocizzare questa procedura dettagliata, in questa procedura secondaria si importa nel proprio repository un altro notebook esistente. Questo notebook esegue le stesse operazioni del notebook precedente, ad eccezione del fatto che questo notebook chiamerà funzioni di codice condiviso archiviate all'esterno del notebook. Anche in questo caso è possibile creare un notebook personalizzato nel proprio repository ed eseguire la condivisione del codice manualmente.

  1. Nel browser Area di lavoro, fare clic con il pulsante destro del mouse sulla cartella notebooks, quindi cliccare Importa.
  2. Nella finestra di dialogo Importa:

    1. Per l'importazione dadi , URL.

    2. Immettere l'URL del contenuto non elaborato del notebook covid_eda_modular nel repository databricks/notebook-best-practices in GitHub. Per get questo URL: i. Andare a https://github.com/databricks/notebook-best-practices. ii. Cliccare la cartella notebooks. iii. Cliccare il file covid_eda_modular.py. iv. Cliccare Raw (Non elaborato). v. Copiare l'URL completo dalla barra degli indirizzi del Web browser nella finestra di dialogo Importa notebook.

      Nota

      La finestra di dialogo Importa notebook funziona con gli URL Git solo per i repository pubblici.

    3. Cliccare Importa.

Passaggio 3.3: Aggiungere le funzioni di codice condiviso di supporto del notebook

  1. Nel browser Area di lavoro fare clic con il pulsante destro del mouse sulla cartella Git best-notebooks, quindi scegliere Crea > Cartella.

  2. Nella finestra di dialogo Nuova cartella immettere covid_analysis, quindi cliccare Crea.

  3. Nella cartella covid_analysis cliccare Crea > File.

  4. Nella finestra di dialogo Nuovo nome file immettere transforms.py, quindi cliccare Crea file.

  5. Nell'editor transforms.pywindowimmettere il codice seguente:

    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

Suggerimento

Per altre tecniche di condivisione del codice, vedere Condividere codice tra notebook di Databricks.

Passaggio 3.4: Aggiungere le dipendenze del codice condiviso

Il codice precedente presenta diverse dipendenze dei pacchetti Python per consentire il corretto funzionamento del codice. In questa procedura secondaria si dichiarano queste dipendenze dei pacchetti. La dichiarazione delle dipendenze migliora la riproducibilità usando versioni definite con precisione delle librerie.

  1. Nel browser Area di lavoro fare clic con il pulsante destro del mouse sulla cartella Git best-notebooks, quindi scegliere Crea > File.

    Nota

    È necessario che il file che elenca le dipendenze dei pacchetti venga inserito nella radice della cartella Git, non nei notebook o nelle cartelle covid_analysis .

  2. Nella finestra di dialogo Nuovo nome file immettere requirements.txt, quindi cliccare Crea file.

  3. Nell'editor di requirements.txtwindow, inserire il codice seguente:

    Nota

    Se il file requirements.txt non è visibile, potrebbe essere necessario refresh web browser.

    -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

    Nota

    Il file precedente elenca versioni specifiche dei pacchetti. Per una migliore compatibilità, è possibile creare riferimenti incrociati tra queste versioni e quelle installate nel cluster multifunzionale. Consultare la sezione "Ambiente di sistema" per la versione di Databricks Runtime del cluster in Versioni e compatibilità delle note sulla versione di Databricks Runtime.

La struttura del repository dovrebbe essere simile alla seguente:

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

Passaggio 3.5: Eseguire il notebook sottoposto a refactoring

In questo passaggio secondario si esegue il notebook covid_eda_modular, che chiama il codice condiviso in covid_analysis/transforms.py.

  1. Nel browser Area di lavoro cliccare il notebook covid_eda_modular all'interno della cartella notebooks.
  2. Select il cluster per collegare questo notebook a.
  3. Cliccare Esegui tutto.
  4. Attendere l'esecuzione del notebook.

Al termine dell'esecuzione del notebook, nel notebook verranno visualizzati risultati simili a quelli del notebook covid_eda_raw: un tracciato dei dati e oltre 600 righe di dati grezzi nel Delta table. La differenza principale di questo notebook è che viene usato un filtro diverso (iso_code di DZA anziché USA). Se il cluster non era già in esecuzione quando si è iniziato a eseguire questo notebook, potrebbero essere necessari alcuni minuti per l'avvio del cluster prima della visualizzazione dei risultati.

  1. Accanto al nome del notebook, cliccare il pulsante del ramo Git first_modules.
  2. Nella finestra di dialogo best-notebooks, nella scheda Modifiche verificare che siano selezionate le opzioni seguenti:
    • requirements.txt
    • covid_analysis/transforms.py
    • notebooks/covid_eda_modular.py
  3. Per Messaggio di commit (obbligatorio), immettere Added refactored notebook.
  4. Per Descrizione (facoltativa), immettere This is the second version of the notebook.
  5. Cliccare Commit e push.
  6. Cliccare il collegamento della richiesta pull in Creare una richiesta pull nel proprio provider Git nel banner.
  7. In GitHub, creare la richiesta pull e unire la richiesta pull nel ramo main.
  8. Tornare all'area di lavoro di Azure Databricks e chiudere la finestra di dialogo best-notebooks se ancora visualizzata.

Passaggio 4: Testare il codice condiviso.

In questo passaggio si testa il codice condiviso creato nel passaggio precedente. Tuttavia, si consiglia di testare questo codice senza eseguire il notebook covid_eda_modular stesso. Ciò è dovuto al fatto che, se non si riesce a eseguire il codice condiviso, è probabile che anche il notebook stesso non possa essere eseguito. Si vogliono rilevare gli errori nel codice condiviso prima di having il notebook principale avrà esito negativo in un secondo momento. Questa tecnica di test è una procedura consigliata per l'ingegneria del software.

Suggerimento

Per ulteriori approcci ai test per i notebook e per informazioni sui test per notebook R e Scala, vedere Unit testing per i notebook.

Passaggio 4.1: Creare un altro ramo di lavoro nel repository

  1. Accanto al nome del notebook, cliccare il pulsante del ramo Git first_modules.
  2. Nella finestra di dialogo best-notebooks, fare clic sulla freccia a discesa accanto al ramo first_modules e selectprincipale.
  3. Cliccare il pulsante Pull. Se viene richiesto di procedere con il pull, cliccare Confirm (Conferma).
  4. Cliccare Crea ramo.
  5. Immettere first_tests e cliccare Create (Crea). (È possibile assegnare al ramo un nome diverso.)
  6. Chiudere questa finestra di dialogo.

Passaggio 4.2: Aggiungere i test

In questo passaggio secondario si usa il framework pytest per testare il codice condiviso. In questi test si asserisce se si ottengono risultati di test specifici. Se un test produce un risultato imprevisto, tale particolare test ha esito negativo sull'asserzione e quindi il test stesso ha esito negativo.

  1. Nel browser Area di lavoro fare clic con il pulsante destro del mouse sulla cartella Git, quindi cliccare Crea > Cartella.

  2. Nella finestra di dialogo Nuova cartella immettere tests, quindi cliccare Crea.

  3. Nella cartella test cliccare Crea > File.

  4. Nella finestra di dialogo Nuovo nome file immettere testdata.csv, quindi cliccare Crea file.

  5. In testdata.csv editor windowimmettere i dati di test seguenti:

    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. Nella cartella test cliccare Crea > File.

  7. Nella finestra di dialogo Nuovo nome file immettere transforms_test.py, quindi cliccare Crea file.

  8. Nel transforms_test.py editor window, inserisci il seguente codice di test. Questi test usano pytest standard e un dataframe pandas fittizio in memoria:

    # 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 struttura del repository dovrebbe essere simile alla seguente:

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

Passaggio 4.3: Eseguire i test

Per velocizzare questa procedura dettagliata, in questa procedura secondaria si usa un notebook importato per eseguire i test precedenti. Questo notebook scarica e installa i pacchetti Python dipendenti dei test nell'area di lavoro, esegue i test e segnala i risultati dei test. Anche se è possibile eseguire pytest dal terminale Web del cluster, l'esecuzione di pytest da un notebook può risultare più pratica.

Nota

L'esecuzione di pytest esegue tutti i file i cui nomi seguono il formato test_*.py o /*_test.py nella directory corrente e nelle relative sottodirectory.

  1. Nel browser Area di lavoro, fare clic con il pulsante destro del mouse sulla cartella notebooks, quindi cliccare Importa.
  2. Nella finestra di dialogo Importa notebook:

    1. Per l'importazione dadi , URL.

    2. Immettere l'URL del contenuto non elaborato del notebook run_unit_tests nel repository databricks/notebook-best-practices in GitHub. Per get questo URL: i. Andare a https://github.com/databricks/notebook-best-practices. ii. Cliccare la cartella notebooks. iii. Cliccare il file run_unit_tests.py. iv. Cliccare Raw (Non elaborato). v. Copiare l'URL completo dalla barra degli indirizzi del Web browser nella finestra di dialogo Importa notebook.

      Nota

      La finestra di dialogo Importa notebook funziona con gli URL Git solo per i repository pubblici.

    3. Cliccare Importa.

  3. Select il cluster per collegare questo notebook a.
  4. Cliccare Esegui tutto.
  5. Attendere l'esecuzione del notebook.

Al termine dell'esecuzione del notebook, nel notebook verranno visualizzate informazioni sul numero di test superati e non superati, insieme ad altri dettagli correlati. Se il cluster non era già in esecuzione quando si è iniziato a eseguire questo notebook, potrebbero essere necessari alcuni minuti per l'avvio del cluster prima della visualizzazione dei risultati.

La struttura del repository dovrebbe essere simile alla seguente:

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  ├── covid_eda_raw (optional)
│  └── run_unit_tests
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py
  1. Accanto al nome del notebook, cliccare il pulsante del ramo Git first_tests.
  2. Nella finestra di dialogo best-notebooks, nella scheda Modifiche verificare che siano selezionate le opzioni seguenti:
    • tests/transforms_test.py
    • notebooks/run_unit_tests.py
    • test/testdata.csv
  3. Per Messaggio di commit (obbligatorio), immettere Added tests.
  4. Per Descrizione (facoltativa), immettere These are the unit tests for the shared code.
  5. Cliccare Commit e push.
  6. Cliccare il collegamento della richiesta pull in Creare una richiesta pull nel proprio provider Git nel banner.
  7. In GitHub, creare la richiesta pull e unire la richiesta pull nel ramo main.
  8. Tornare all'area di lavoro di Azure Databricks e chiudere la finestra di dialogo best-notebooks se ancora visualizzata.

Passaggio 5: Creare un processo per eseguire i notebook

Nelle fasi precedenti, si è testato manualmente il codice condiviso e si sono eseguiti manualmente i notebook. In questo passaggio si usa un processo di Azure Databricks per testare il codice condiviso ed eseguire automaticamente i notebook, su richiesta o in base a una pianificazione regolare.

Passaggio 5.1: Creare un task di processo per eseguire il notebook di test

  1. Nella barra laterale dell'area di lavoro, cliccare Flussi di lavoro.
  2. Nella scheda Processi cliccare Crea processo.
  3. Modificare il nome del lavoro in modo che sia covid_report.
  4. Per Nome task immettere run_notebook_tests.
  5. Per tipo, selectnotebook.
  6. Per Source, selectfornitore Git.
  7. Cliccare Aggiungi un riferimento git.
  8. Nella finestra di dialogo Informazioni su Git:
    1. Per URL repository Git immettere l'URL Clone with HTTPS (Clona con HTTPS) di GitHub del proprio repository GitHub. Questo articolo presuppone che l'URL termini con best-notebooks.git, ad esempio https://github.com/<your-GitHub-username>/best-notebooks.git.
    2. Per provider Git, selectGitHub.
    3. Per Riferimento Git (ramo/tag/commit), immettere main.
    4. Accanto a riferimento Git (ramo/tag/commit), selectramo.
    5. Cliccare Conferma.
  9. In Percorso immettere notebooks/run_unit_tests. Non aggiungere l'estensione di file .py.
  10. Per Cluster, select il cluster del passaggio precedente.
  11. Cliccare Crea task.

Nota

In questo scenario, Databricks sconsiglia di utilizzare il pulsante di pianificazione nel notebook, come descritto in Creare e gestire processi di notebook pianificati per pianificare un processo con cui eseguire periodicamente questo notebook. Il motivo è che il pulsante di pianificazione crea un processo usando la copia di lavoro più recente del notebook presente nel repository dell'area di lavoro. Databricks consiglia invece di seguire le istruzioni precedenti per creare un processo che usa la versione di commit più recente del notebook presente nel repository.

Passaggio 5.2: Creare un task di processo per eseguire il notebook principale

  1. Cliccare l'icona + Aggiungi task.
  2. Viene visualizzato un menu a comparsa. Select Taccuino.
  3. Per Nome task immettere run_main_notebook.
  4. Per tipo, selectnotebook.
  5. In Percorso immettere notebooks/covid_eda_modular. Non aggiungere l'estensione di file .py.
  6. Per Cluster, select il cluster del passaggio precedente.
  7. Verificare che il valore di dipende darun_notebook-tests.
  8. Cliccare Crea task.

Passaggio 5.3 Eseguire il processo

  1. Cliccare Run now (Esegui adesso).

  2. Nella finestra popup cliccare Visualizza esecuzione.

    Nota

    Se il popup scompare troppo rapidamente, procedere come segue:

    1. Sulla barra laterale nell'ambiente Data Science & Engineering o Databricks Mosaic AI cliccare Flussi di lavoro.
    2. Nella scheda Processo viene eseguito fare clic sul valore ora di inizio per il processo più recente con covid_report nelprocessi di .

  3. Per visualizzare i risultati del processo, cliccarel riquadro run_notebook_tests , sul riquadro run_main_notebook o su entrambi. I risultati su ciascun riquadro sono gli stessi che si otterrebbero eseguendo i notebook manualmente uno per uno.

Nota

Questo processo è stato eseguito su richiesta. Per set impostare questo processo per l'esecuzione regolare, vedere Automatizzare i processi con pianificazioni e trigger.

(Facoltativo) Passaggio 6: Set il repository per testare il codice ed eseguire automaticamente il notebook ogni volta che il codice cambia

Nel passaggio precedente è stato usato un processo per testare automaticamente il codice condiviso ed eseguire i notebook in un momento specifico o ricorrente. Tuttavia, è preferibile attivare automaticamente i test quando le modifiche vengono unite nel repository GitHub, usando uno strumento CI/CD come GitHub Actions.

Passaggio 6.1: Set l'accesso a GitHub all'area di lavoro

In questo passaggio secondario si set un flusso di lavoro di GitHub Actions che esegue processi nell'area di lavoro ogni volta che le modifiche vengono unite nel repository. A tale scopo, è possibile concedere a GitHub un token di Azure Databricks univoco per l'accesso.

Per motivi di sicurezza, Databricks sconsiglia l'assegnazione del token di accesso personale dell'utente dell'area di lavoro di Azure Databricks a GitHub. Databricks consiglia invece di assegnare a GitHub un token Microsoft Entra ID associato a un'entità servizio Microsoft Entra ID. Per istruzioni, vedere la sezione Azure della pagina Azione GitHub Esegui notebook di Databricks nel Marketplace di GitHub Actions.

Importante

I notebook vengono eseguiti con tutte le autorizzazioni dell'area di lavoro dell'identità associata al token; pertanto, Databricks consiglia di usare un'entità servizio. Se si vuole concedere al proprio utente dell'area di lavoro di Azure Databricks il token di accesso personale a GitHub solo a scopo di esplorazione personale e si è consapevoli che per motivi di sicurezza Databricks sconsiglia questa procedura, vedere le istruzioni Autenticazione con token di accesso personale di Databricks.

Passaggio 6.2: Aggiungere il flusso di lavoro di GitHub Actions

In questa procedura secondaria si aggiunge un flusso di lavoro di GitHub Actions per eseguire il notebook run_unit_tests ogni volta che è presente una richiesta pull al repository.

Questo passaggio secondario memorizza il flusso di lavoro di GitHub Actions in un file archiviato all'interno di più livelli di cartelle nel repository GitHub. Per funzionare correttamente, GitHub Actions richiede che nel repository esista una gerarchia di cartelle nidificata specifica. Per completare questo passaggio, è necessario usare il sito Web per il repository GitHub, perché l'interfaccia utente della cartella Git di Azure Databricks non supporta la creazione di gerarchie di cartelle annidate.

  1. Nel sito Web del repository GitHub, cliccare la scheda Code.

  2. Fare clic sulla freccia accanto a principale per espandere il menu a tendina Cambia rami o taglist.

  3. Nella casella Find or create a branch, immettere adding_github_actions.

  4. Cliccare Create branch: adding_github_actions from ‘main’.

  5. Cliccare Add file > Create new file.

  6. Per Name your file, immettere .github/workflows/databricks_pull_request_tests.yml.

  7. Nell'editor windowimmettere il codice seguente. Questo codice usa l'hook pull_request da Azione GitHub Esegui notebook di Databricks per eseguire il notebook run_unit_tests.

    Nel codice seguente, sostituire:

    • <your-workspace-instance-URL> con il nome dell'istanza di Azure Databricks.
    • <your-access-token> con il token generato in precedenza.
    • <your-cluster-id> con l'ID del cluster di destinazione.
    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. Cliccare Commit changes.

  9. Nella finestra di dialogo Commit changes, immettere Create databricks_pull_request_tests.yml in Commit message

  10. Select Esegui il commit direttamente nel ramo adding_github_actions e fai clic su Conferma le modifiche.

  11. Nella scheda Code, cliccare Compare & pull request (Confronto e richiesta pull), quindi creare la richiesta pull.

  12. Nella pagina della richiesta pull, attendere che l'icona accanto a Esegui test di Databricks / unit-test-notebook (pull_request) visualizzi un segno di spunta verde. (Potrebbero essere necessari alcuni istanti per visualizzare l'icona.) Se è presente una X rossa anziché un segno di spunta verde, cliccare Dettagli per scoprire perché. Se l'icona o i Dettagli non vengono più visualizzati, cliccare Mostra tutti i controlli.

  13. Se viene visualizzato il segno di spunta verde, unire la richiesta pull nel ramo main.

(Facoltativo) Passaggio 7: Update il codice condiviso in GitHub per attivare i test

In questo passaggio si apporta una modifica al codice condiviso e quindi si esegue il push della modifica nel repository GitHub; questa azione attiva immediatamente i test automatici, in base all'azione GitHub del passaggio precedente.

Passaggio 7.1: Creare un altro ramo di lavoro nel repository

  1. Dal browser Area di lavoro, aprire la cartella Git best-notebooks.
  2. Accanto al nome della cartella, cliccare il pulsante del ramo Git first_tests.
  3. Nella finestra di dialogo best-notebooks, fare clic sulla freccia a discesa accanto al ramo first_tests e selectprincipale.
  4. Cliccare il pulsante Pull. Se viene richiesto di procedere con il pull, cliccare Confirm (Conferma).
  5. Cliccare il pulsante + (Create branch) (Crea ramo).
  6. Immettere trigger_tests e cliccare Create (Crea). (È possibile assegnare al ramo un nome diverso.)
  7. Chiudere questa finestra di dialogo.

Passaggio 7.2: Modificare il codice condiviso

  1. Nel browser Area di lavoro, nella cartella Git best-notebooks, cliccarel file covid_analysis/transforms.py.

  2. Modificare la terza riga del file:

    # Filter by country code.

    In questa:

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

Passaggio 7.3: Eseguire il check-in della modifica per attivare i test

  1. Accanto al nome del file, cliccare il pulsante del ramo Git trigger_tests.
  2. Nella finestra di dialogo best-notebooks, nella scheda Modifiche verificare che sia selezionato covid_analysis/transforms.py.
  3. Per Messaggio di commit (obbligatorio), immettere Updated comment.
  4. Per Descrizione (facoltativa), immettere This updates the comment for filter_country.
  5. Cliccare Commit e push.
  6. Cliccare il collegamento della richiesta pull in Creare una richiesta pull nel proprio provider Git nel banner, quindi creare la richiesta pull in GitHub.
  7. Nella pagina della richiesta pull, attendere che l'icona accanto a Esegui test di Databricks / unit-test-notebook (pull_request) visualizzi un segno di spunta verde. (Potrebbero essere necessari alcuni istanti per visualizzare l'icona.) Se è presente una X rossa anziché un segno di spunta verde, cliccare Dettagli per scoprire perché. Se l'icona o i Dettagli non vengono più visualizzati, cliccare Mostra tutti i controlli.
  8. Se viene visualizzato il segno di spunta verde, unire la richiesta pull nel ramo main.