Osvědčené postupy pro softwarové inženýrství pro poznámkové bloky

Tento článek obsahuje praktické názorné postupy, které ukazují, jak aplikovat osvědčené postupy softwarového inženýrství na poznámkové bloky Azure Databricks, včetně správy verzí, sdílení kódu, testování a volitelné kontinuální integrace a průběžného doručování nebo nasazování (CI/CD).

Tento návod vám ukáže, jak:

• Přidání poznámkových bloků do složek Git Azure Databricks pro správu verzí
• Extrahujte části kódu z jednoho z poznámkových bloků do modulu, který lze sdílet.
• Otestujte sdílený kód.
• Spusťte poznámkové bloky z úlohy Azure Databricks.
• Volitelně můžete na sdílený kód použít CI/CD.

Požadavky

K dokončení tohoto názorného postupu je nutné zadat následující zdroje informací:

• Vzdálené úložiště s poskytovatelem Gitu, které Databricks podporuje. Tento článek popisuje použití GitHubu. Tento názorný postup předpokládá, že máte k dispozici úložiště best-notebooks GitHub. (Úložiště můžete pojmenovat jinak. Pokud to uděláte, nahraďte best-notebooks v tomto názorném postupu názvem svého úložiště.) Pokud ho ještě nemáte, vytvořte úložiště GitHub.

  Poznámka:

  Pokud vytvoříte nové úložiště, nezapomeňte úložiště inicializovat alespoň jedním souborem, například souborem README .

• Pracovní prostor Azure Databricks Pokud ho ještě nemáte, vytvořte pracovní prostor .

• Cluster Azure Databricks pro všechny účely v pracovním prostoru. Pokud chcete spouštět poznámkové bloky během fáze návrhu, připojíte je ke spuštěném clusteru pro všechny účely. Později tento názorný postup používá úlohu Azure Databricks k automatizaci spouštění poznámkových bloků v tomto clusteru. (Můžete také spouštět úlohy v clusterech úloh, které existují pouze pro životnost úloh.) Pokud ho ještě nemáte, vytvořte cluster pro všechny účely.

Krok 1: Nastavení složek Git v Databricks

V tomto kroku připojíte existující úložiště GitHubu ke složkám Git Azure Databricks v existujícím pracovním prostoru Azure Databricks.

Pokud chcete, aby se váš pracovní prostor mohl připojit k úložišti GitHub, musíte nejprve zadat svůj pracovní prostor s přihlašovacími údaji GitHubu, pokud jste to ještě neudělali.

Krok 1.1: Zadání přihlašovacích údajů GitHubu

1. Klikněte na své uživatelské jméno v pravém horním rohu pracovního prostoru a potom v rozevíracím seznamu klikněte na Nastavení.
2. Na bočním panelu Nastavení v části Uživatel klikněte na Propojené účty.
3. V části integrace Gituvyberte pro poskytovatele GituGitHub.
4. Klikněte na osobní přístupový token.
5. Jako uživatelské jméno nebo e-mail poskytovatele Gitu zadejte uživatelské jméno GitHubu.
6. Jako token zadejte osobní přístupový token GitHubu (classic). Tento osobní přístupový token (classic) musí mít oprávnění úložiště a pracovního postupu .
7. Klikněte na Uložit.

Krok 1.2: Připojení k úložišti GitHub

1. Na bočním panelu pracovního prostoru klikněte na Pracovní prostor.
2. V prohlížeči pracovního prostoru rozbalte položku > pracovního prostoru.
3. Klikněte pravým tlačítkem na složku uživatelského jména a potom klikněte na Vytvořit > složku Git.
4. V dialogovém okně Vytvořit složku Gitu:
   1. Jako adresu URL úložiště Git zadejte GitHub Clone s adresou URL HTTPS pro úložiště GitHub. Tento článek předpokládá, že vaše adresa URL končí best-notebooks.git, například https://github.com/<your-GitHub-username>/best-notebooks.git.
   2. V poskytovatele Gitu vyberte GitHubu .
   3. Ponechte název složky Git nastavený na název úložiště, například best-notebooks.
   4. Klikněte na Vytvořit složku Git.

Krok 2: Import a spuštění poznámkového bloku

V tomto kroku naimportujete do úložiště existující externí poznámkový blok. Pro tento názorný postup můžete vytvořit vlastní poznámkové bloky, ale abychom vám je zde poskytli, urychlíme.

Krok 2.1: Vytvoření pracovní větve v úložišti

V tomto dílčím kroku vytvoříte větev s názvem eda v úložišti. Tato větev umožňuje pracovat se soubory a kódem nezávisle na větvi úložiště main , což je osvědčený postup pro softwarové inženýrství. (Větev můžete pojmenovat jinak.)

1. Složka Git z kroku 1.2 by měla být otevřená. Pokud ne, pak na bočním panelu pracovního prostoru rozbalte > pracovního prostoru, rozbalte složku uživatelského jména a klikněte na složku Git.

2. Vedle názvu složky pod navigačním popisem cesty pracovního prostoru klikněte na hlavní tlačítko větve Git.

3. V dialogovém okně nejlepších poznámkových bloků klikněte na tlačítko Vytvořit větev .

   Poznámka:

   Pokud má vaše úložiště jiný název než best-notebooks, název tohoto dialogového okna se bude lišit, tady a v tomto názorném postupu.

4. Zadejte edaa klikněte na Vytvořit.

5. Zavřete toto dialogové okno.

Krok 2.2: Import poznámkového bloku do úložiště

V tomto dílčím kroku naimportujete existující poznámkový blok z jiného úložiště do úložiště. Tento poznámkový blok provede následující:

• Zkopíruje soubor CSV z úložiště GitHubu owid/covid-19-data do clusteru ve vašem pracovním prostoru. Tento soubor CSV obsahuje veřejná data o nemocnicích COVID-19 a metrikách intenzivní péče z celého světa.
• Načte obsah souboru CSV do datového rámce pandas.
• Filtruje data tak, aby obsahovala metriky pouze z USA.
• Zobrazí graf dat.
• Uloží datový rámec pandas jako rozhraní PANDAS API do datového rámce Spark.
• Provádí čištění dat v rozhraní Pandas API v datovém rámci Sparku.
• Zapíše rozhraní Pandas API do datového rámce Sparku jako tabulku Delta ve vašem pracovním prostoru.
• Zobrazí obsah tabulky Delta.

I když tady můžete ve svém úložišti vytvořit vlastní poznámkový blok, import existujícího poznámkového bloku vám pomůže tento názorný postup urychlit. Pokud chcete vytvořit poznámkový blok v této větvi nebo přesunout existující poznámkový blok do této větve místo importu poznámkového bloku, přečtěte si téma Základní použití souborů pracovního prostoru.

1. Ve složce Git s nejlepšími poznámkovými bloky klikněte na Vytvořit > složku.
2. V dialogovém okně Nová složka zadejte notebooksa klepněte na tlačítko Vytvořit.
3. Ve složce poznámkových bloků klikněte na kebab a pak naimportujte.
4. V dialogovém okně Importovat :

   1. Pokud chcete Importovat z, vyberte adresy URL .

   2. Zadejte adresu URL nezpracovaného obsahu poznámkového covid_eda_raw bloku v úložišti na databricks/notebook-best-practices GitHubu. Chcete-li získat tuto adresu URL: Přejděte na https://github.com/databricks/notebook-best-practices . ii. Klikněte na notebooks složku. iii. Klikněte na covid_eda_raw.py soubor. iv. Klikněte na Nezpracované. v. Zkopírujte úplnou adresu URL z adresního řádku webového prohlížeče do dialogového okna Importovat .

      Poznámka:

      Dialogové okno Import funguje jenom s adresami URL Gitu pro veřejná úložiště.

   3. Klepněte na tlačítko Import.

Krok 2.3: Spuštění poznámkového bloku

1. Pokud se poznámkový blok ještě nezobrazuje, otevřete složku poznámkových bloků a klikněte na covid_eda_raw poznámkový blok uvnitř složky.
2. Vyberte cluster, ke kterému chcete tento poznámkový blok připojit. Pokyny k vytvoření clusteru najdete v tématu Vytvoření clusteru.
3. Klikněte na Spustit vše.
4. Počkejte, než se poznámkový blok spustí.

Po dokončení spuštění poznámkového bloku by se v poznámkovém bloku měl zobrazit graf dat i více než 600 řádků nezpracovaných dat v tabulce Delta. Pokud cluster ještě nebyl spuštěný při spuštění tohoto poznámkového bloku, spuštění clusteru může trvat několik minut, než se zobrazí výsledky.

Krok 2.4: Vrácení poznámkového bloku se změnami a jejich sloučením

V tomto dílčím kroku uložíte svou práci do svého úložiště GitHub. Poznámkový blok pak sloučíte z pracovní větve do větve úložiště main .

1. Vedle názvu poznámkového bloku klikněte na tlačítko větve Gitu eda .
2. V dialogovém okně nejlepších poznámkových bloků na kartě Změny se ujistěte, že je vybraný soubor poznámkových bloků/covid_eda_raw.py.
3. Pro potvrzení zprávy (povinné) zadejte Added raw notebook.
4. Jako popis (volitelné) zadejte This is the first version of the notebook.
5. Klikněte na Potvrdit a nasdílení změn.
6. V banneru klikněte na odkaz žádosti o přijetí změn v části Vytvoření žádosti o přijetí změn u svého poskytovatele Gitu.
7. Na GitHubu vytvořte žádost o přijetí změn a pak žádost o přijetí změn sloučíte do main větve.
8. Zpátky v pracovním prostoru Azure Databricks zavřete dialogové okno nejlepších poznámkových bloků, pokud se stále zobrazuje.

Krok 3: Přesunutí kódu do sdíleného modulu

V tomto kroku přesunete část kódu v poznámkovém bloku do sady sdílených funkcí mimo poznámkový blok. Díky tomu můžete tyto funkce používat s dalšími podobnými poznámkovými bloky, které můžou urychlit budoucí kódování a zajistit předvídatelnější a konzistentnější výsledky poznámkových bloků. Sdílení tohoto kódu vám také umožňuje snadněji testovat tyto funkce, což jako osvědčený postup softwarového inženýrství může zvýšit celkovou kvalitu kódu při práci.

Krok 3.1: Vytvoření další pracovní větve v úložišti

1. Vedle názvu poznámkového bloku klikněte na tlačítko větve Gitu eda .
2. V dialogovém okně nejlepších notebooků klikněte na šipku rozevíracího seznamu vedle větve eda a vyberte "main".
3. Klikněte na tlačítko Vyžádat . Pokud se zobrazí výzva k pokračování stahování, klikněte na Potvrdit.
4. Klikněte na tlačítko Vytvořit větev .
5. Zadejte first_modulesa klikněte na Vytvořit. (Větev můžete pojmenovat jinak.)
6. Zavřete toto dialogové okno.

Krok 3.2: Import poznámkového bloku do úložiště

Pokud chcete tento názorný postup urychlit, naimportujete do úložiště další existující poznámkový blok. Tento poznámkový blok dělá totéž jako předchozí poznámkový blok, s výjimkou tohoto poznámkového bloku bude volat funkce sdíleného kódu, které jsou uložené mimo poznámkový blok. Znovu můžete v úložišti vytvořit vlastní poznámkový blok a udělat si vlastní sdílení kódu sami.

1. V prohlížeči pracovního prostoru klikněte pravým tlačítkem myši na složku poznámkových bloků a potom klikněte na Importovat.
2. V dialogovém okně Importovat :

   1. Pokud chcete Importovat z, vyberte adresy URL .

   2. Zadejte adresu URL nezpracovaného obsahu poznámkového covid_eda_modular bloku v úložišti na databricks/notebook-best-practices GitHubu. Chcete-li získat tuto adresu URL: Přejděte na https://github.com/databricks/notebook-best-practices . ii. Klikněte na notebooks složku. iii. Klikněte na covid_eda_modular.py soubor. iv. Klikněte na Nezpracované. v. Zkopírujte úplnou adresu URL z adresního řádku webového prohlížeče do dialogového okna Importovat poznámkové bloky .

      Poznámka:

      Dialogové okno Importovat poznámkové bloky funguje jenom s adresami URL Gitu pro veřejná úložiště.

   3. Klepněte na tlačítko Import.

Krok 3.3: Přidání podpůrných funkcí sdíleného kódu poznámkového bloku

1. V prohlížeči pracovního prostoru klikněte pravým tlačítkem myši na složku Git s nejlepšími poznámkovými bloky a potom klikněte na Vytvořit > složku.

2. V dialogovém okně Nová složka zadejte covid_analysisa klepněte na tlačítko Vytvořit.

3. Ve složce covid_analysis klikněte na Vytvořit > soubor.

4. V dialogovém okně Nový název souboru zadejte transforms.pya klepněte na tlačítko Vytvořit soubor.

5. V okně editoru transforms.py zadejte následující kód:

   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
   

Krok 3.4: Přidání závislostí sdíleného kódu

Předchozí kód obsahuje několik závislostí balíčku Pythonu, které umožní správné spuštění kódu. V tomto dílčím kroku deklarujete tyto závislosti balíčků. Deklarace závislostí zlepšuje reprodukovatelnost pomocí přesně definovaných verzí knihoven.

1. V prohlížeči pracovního prostoru klikněte pravým tlačítkem na složku Git s nejlepšími poznámkovými bloky a potom klikněte na Vytvořit > soubor.

   Poznámka:

   Chcete, aby soubor se seznamem závislostí balíčků přešel do kořenové složky Gitu, ne do poznámkových bloků nebo covid_analysis složek.

2. V dialogovém okně Nový název souboru zadejte requirements.txta klepněte na tlačítko Vytvořit soubor.

3. V okně editoru requirements.txt zadejte následující kód:

   Poznámka:

   Pokud requirements.txt soubor není viditelný, možná budete muset aktualizovat webový prohlížeč.

   -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
   

   Poznámka:

   Předchozí soubor obsahuje seznam konkrétních verzí balíčků. Kvůli lepší kompatibilitě můžete tyto verze křížově odkazovat s verzemi, které jsou nainstalované v clusteru pro všechny účely. Informace o verzi Databricks Runtime vašeho clusteru najdete v části Systémové prostředí ve verzích a kompatibilitě modulu Databricks Runtime.

Struktura úložiště by teď měla vypadat takto:

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

Krok 3.5: Spuštění refaktorovaného poznámkového bloku

V tomto dílčím covid_eda_modular kroku spustíte poznámkový blok, který volá sdílený kód v covid_analysis/transforms.pysouboru .

1. V prohlížeči pracovního prostoru klikněte na covid_eda_modular poznámkový blok ve složce poznámkových bloků.
2. Vyberte cluster, ke kterému chcete tento poznámkový blok připojit.
3. Klikněte na Spustit vše.
4. Počkejte, než se poznámkový blok spustí.

Po dokončení spuštění poznámkového bloku by se v poznámkovém bloku měly zobrazit podobné výsledky jako covid_eda_raw poznámkový blok: graf dat a více než 600 řádků nezpracovaných dat v tabulce Delta. Hlavním rozdílem v tomto poznámkovém bloku je, že se používá jiný filtr (místo iso_codeDZAUSA). Pokud cluster ještě nebyl spuštěný při spuštění tohoto poznámkového bloku, spuštění clusteru může trvat několik minut, než se zobrazí výsledky.

Krok 3.6: Vrácení poznámkového bloku a souvisejícího kódu se změnami

1. Vedle názvu poznámkového bloku klikněte na tlačítko first_modules větev Gitu.
2. V dialogovém okně nejlepších poznámkových bloků na kartě Změny se ujistěte, že jsou vybrány následující položky:
   • requirements.txt
   • covid_analysis/transforms.py
   • poznámkové bloky/covid_eda_modular.py
3. Pro potvrzení zprávy (povinné) zadejte Added refactored notebook.
4. Jako popis (volitelné) zadejte This is the second version of the notebook.
5. Klikněte na Potvrdit a nasdílení změn.
6. V banneru klikněte na odkaz žádosti o přijetí změn v části Vytvoření žádosti o přijetí změn u svého poskytovatele Gitu.
7. Na GitHubu vytvořte žádost o přijetí změn a pak žádost o přijetí změn sloučíte do main větve.
8. Zpátky v pracovním prostoru Azure Databricks zavřete dialogové okno nejlepších poznámkových bloků, pokud se stále zobrazuje.

Krok 4: Testování sdíleného kódu

V tomto kroku otestujete sdílený kód z posledního kroku. Tento kód ale chcete otestovat bez spuštění samotného poznámkového covid_eda_modular bloku. Důvodem je to, že pokud se sdílený kód nepodaří spustit, samotný poznámkový blok se pravděpodobně nepodaří spustit. Chcete nejprve zachytit chyby ve svém sdíleném kódu, než se váš hlavní poznámkový blok později nezdaří. Tato technika testování je osvědčeným postupem softwarového inženýrství.

Krok 4.1: Vytvoření další pracovní větve v úložišti

1. Vedle názvu poznámkového bloku klikněte na tlačítko first_modules větev Gitu.
2. V dialogovém okně nejlepších poznámkových bloků klikněte na šipku rozevíracího seznamu vedle větve first_modules a vyberte hlavní.
3. Klikněte na tlačítko Vyžádat . Pokud se zobrazí výzva k pokračování stahování, klikněte na Potvrdit.
4. Klikněte na Vytvořit větev.
5. Zadejte first_testsa klikněte na Vytvořit. (Větev můžete pojmenovat jinak.)
6. Zavřete toto dialogové okno.

Krok 4.2: Přidání testů

V tomto dílčím kroku použijete k otestování sdíleného kódu architekturu pytest . V těchto testech určíte, zda jsou dosaženy konkrétní výsledky testů. Pokud některý test vytvoří neočekávaný výsledek, tento konkrétní test kontrolní výraz selže, a proto samotný test selže.

1. V prohlížeči pracovního prostoru klikněte pravým tlačítkem na složku Git a potom klikněte na Vytvořit > složku.

2. V dialogovém okně Nová složka zadejte testsa klepněte na tlačítko Vytvořit.

3. Ve složce testy klikněte na Vytvořit > soubor.

4. V dialogovém okně Nový název souboru zadejte testdata.csva klepněte na tlačítko Vytvořit soubor.

5. V okně editoru testdata.csv zadejte následující testovací data:

   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. Ve složce testy klikněte na Vytvořit > soubor.

7. V dialogovém okně Nový název souboru zadejte transforms_test.pya klepněte na tlačítko Vytvořit soubor.

8. V okně editoru transforms_test.py zadejte následující testovací kód. Tyto testy používají standardní pytestpříslušenství a také napodobený datový rámec pandas v paměti:

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

Struktura úložiště by teď měla vypadat takto:

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

Krok 4.3: Spuštění testů

Chcete-li tento názorný postup urychlit, použijete v tomto dílčím kroku importovaný poznámkový blok ke spuštění předchozích testů. Tento poznámkový blok stáhne a nainstaluje závislé balíčky Pythonu testů do pracovního prostoru, spustí testy a nahlásí výsledky testů. I když byste mohli běžet pytest z webového terminálu clusteru, pytest spouštění z poznámkového bloku může být pohodlnější.

1. V prohlížeči pracovního prostoru klikněte pravým tlačítkem myši na složku poznámkových bloků a potom klikněte na Importovat.
2. V dialogovém okně Importovat poznámkové bloky :

   1. Pokud chcete Importovat z, vyberte adresy URL .

   2. Zadejte adresu URL nezpracovaného obsahu poznámkového run_unit_tests bloku v úložišti na databricks/notebook-best-practices GitHubu. Chcete-li získat tuto adresu URL: Přejděte na https://github.com/databricks/notebook-best-practices . ii. Klikněte na notebooks složku. iii. Klikněte na run_unit_tests.py soubor. iv. Klikněte na Nezpracované. v. Zkopírujte úplnou adresu URL z adresního řádku webového prohlížeče do dialogového okna Importovat poznámkové bloky .

      Poznámka:

      Dialogové okno Importovat poznámkové bloky funguje jenom s adresami URL Gitu pro veřejná úložiště.

   3. Klepněte na tlačítko Import.

3. Vyberte cluster, ke kterému chcete tento poznámkový blok připojit.
4. Klikněte na Spustit vše.
5. Počkejte, než se poznámkový blok spustí.

Po dokončení spuštění poznámkového bloku by se v poznámkovém bloku měly zobrazit informace o počtu úspěšného a neúspěšného testu spolu s dalšími souvisejícími podrobnostmi. Pokud cluster ještě nebyl spuštěný při spuštění tohoto poznámkového bloku, spuštění clusteru může trvat několik minut, než se zobrazí výsledky.

Struktura úložiště by teď měla vypadat takto:

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

Krok 4.4: Vrácení poznámkového bloku a souvisejících testů

1. Vedle názvu poznámkového bloku klikněte na tlačítko first_tests větev Gitu.
2. V dialogovém okně nejlepších poznámkových bloků na kartě Změny se ujistěte, že jsou vybrány následující položky:
   • testy/transforms_test.py
   • poznámkové bloky/run_unit_tests.py
   • testy/testdata.csv
3. Pro potvrzení zprávy (povinné) zadejte Added tests.
4. Jako popis (volitelné) zadejte These are the unit tests for the shared code..
5. Klikněte na Potvrdit a nasdílení změn.
6. V banneru klikněte na odkaz žádosti o přijetí změn v části Vytvoření žádosti o přijetí změn u svého poskytovatele Gitu.
7. Na GitHubu vytvořte žádost o přijetí změn a pak žádost o přijetí změn sloučíte do main větve.
8. Zpátky v pracovním prostoru Azure Databricks zavřete dialogové okno nejlepších poznámkových bloků, pokud se stále zobrazuje.

Krok 5: Vytvoření úlohy pro spuštění poznámkových bloků

V předchozích krocích jste sdílený kód ručně otestovali a spustili poznámkové bloky ručně. V tomto kroku použijete úlohu Azure Databricks k otestování sdíleného kódu a automatickému spuštění poznámkových bloků, a to buď na vyžádání, nebo podle běžného plánu.

Krok 5.1: Vytvoření úlohy pro spuštění testovacího poznámkového bloku

1. Na bočním panelu pracovního prostoru klikněte na Pracovní postupy.
2. Na kartě Úlohy klikněte na Vytvořit úlohu.
3. Upravte název úlohy, která má být covid_report.
4. Jako název úkolu zadejte run_notebook_tests.
5. Pro typvyberte Notebook .
6. U zdrojovéhovyberte poskytovatele Gitu.
7. Klikněte na Přidat odkaz gitu.
8. V dialogovém okně s informacemi o Gitu:
   1. Jako adresu URL úložiště Git zadejte GitHub Clone s adresou URL HTTPS pro úložiště GitHub. Tento článek předpokládá, že vaše adresa URL končí best-notebooks.git, například https://github.com/<your-GitHub-username>/best-notebooks.git.
   2. V poskytovatele Gitu vyberte GitHubu .
   3. Jako referenční informace k Gitu (větev / značka / potvrzení) zadejte main.
   4. Vedle reference Gitu (větev / značka / potvrzení)vyberte větev .
   5. Klikněte na tlačítko Potvrdit.
9. Do cesty zadejte notebooks/run_unit_tests. Nepřidávejte příponu .py souboru.
10. V clusteruvyberte cluster z předchozího kroku.
11. Klikněte na Vytvořit úkol.

Krok 5.2: Vytvoření úlohy pro spuštění hlavního poznámkového bloku

1. Klikněte na ikonu + Přidat úkol .
2. Zobrazí se místní nabídka. Vyberte poznámkový blok.
3. Jako název úkolu zadejte run_main_notebook.
4. Pro typvyberte Notebook .
5. Do cesty zadejte notebooks/covid_eda_modular. Nepřidávejte příponu .py souboru.
6. V clusteruvyberte cluster z předchozího kroku.
7. Ověřte , že hodnota závisí na hodnotě run_notebook-tests.
8. Klikněte na Vytvořit úkol.

Krok 5.3 Spuštění úlohy

1. Klikněte na možnost Spustit.

2. V automaticky otevíraném okně klikněte na Zobrazit spustit.

   Poznámka:

   Pokud automaticky otevírané okno zmizí příliš rychle, postupujte takto:

   1. Na bočním panelu v prostředí Datová Věda & Engineering nebo Databricks Mosaic AI klikněte na Pracovní postupy.
   2. Na kartě Spuštění úloh klikněte na hodnotu ve sloupci Čas zahájení u nejnovější úlohy s covid_report ve sloupci Úlohy.

3. Pokud chcete zobrazit výsledky úlohy, klikněte na dlaždici run_notebook_tests , na dlaždici run_main_notebook nebo na obojí. Výsledky na každé dlaždici jsou stejné, jako kdybyste poznámkové bloky spustili sami, jeden po druhém.

(Volitelné) Krok 6: Nastavení úložiště pro otestování kódu a spuštění poznámkového bloku automaticky při každé změně kódu

V předchozím kroku jste použili úlohu k automatickému otestování sdíleného kódu a spouštění poznámkových bloků v určitém okamžiku nebo opakovaně. Pokud se ale změny sloučí do úložiště GitHubu, můžete chtít testy aktivovat automaticky pomocí nástroje CI/CD, jako je GitHub Actions.

Krok 6.1: Nastavení přístupu GitHubu k vašemu pracovnímu prostoru

V tomto dílčím kroku nastavíte pracovní postup GitHub Actions, který spouští úlohy v pracovním prostoru při každém sloučení změn do úložiště. Uděláte to tak, že GitHubu udělíte jedinečný token Azure Databricks pro přístup.

Z bezpečnostních důvodů vám Databricks nedoporučuje dát uživateli osobního přístupového tokenu pracovního prostoru Azure Databricks na GitHub. Databricks místo toho doporučuje, abyste GitHubu dali token ID Microsoft Entra, který je přidružený k instančnímu objektu Microsoft Entra ID. Pokyny najdete v části Azure na stránce Akce GitHubu pro spuštění poznámkového bloku Databricks na Marketplace GitHub Actions.

Krok 6.2: Přidání pracovního postupu GitHub Actions

V tomto dílčím kroku přidáte pracovní postup GitHub Actions ke spuštění run_unit_tests poznámkového bloku vždy, když do úložiště existuje žádost o přijetí změn.

Tento dílčí krok ukládá pracovní postup GitHub Actions do souboru uloženého v několika úrovních složek v úložišti GitHub. Aby služba GitHub Actions fungovala správně, vyžaduje v úložišti konkrétní hierarchii vnořených složek. K dokončení tohoto kroku musíte použít web pro úložiště GitHub, protože uživatelské rozhraní složky Azure Databricks Git nepodporuje vytváření vnořených hierarchií složek.

1. Na webu úložiště GitHub klikněte na kartu Kód .

2. Klikněte na šipku vedle hlavní a rozbalte rozevírací seznam Přepnout větve nebo tagy.

3. Do pole Najít nebo vytvořit větev zadejte adding_github_actions.

4. Klikněte na Vytvořit větev: adding_github_actions z hlavní větve.

5. Klikněte na Přidat soubor > Vytvořit nový soubor.

6. Jako název souboru zadejte .github/workflows/databricks_pull_request_tests.yml.

7. V okně editoru zadejte následující kód. Tento kód používá pull_request háku z akce GitHubu Spustit poznámkový blok Databricks ke spuštění poznámkového run_unit_tests bloku.

   V následujícím kódu nahraďte:

   • <your-workspace-instance-URL>s názvem vaší instance Azure Databricks.
   • <your-access-token> s tokenem, který jste vygenerovali dříve.
   • <your-cluster-id>s ID cílového clusteru.

   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. Klikněte na Potvrdit změny.

9. V dialogovém okně Potvrdit změny zadejte Create databricks_pull_request_tests.yml zprávu Potvrzení.

10. Vyberte Potvrdit přímo do větve adding_github_actions a klikněte na Potvrdit změny.

11. Na kartě Kód klikněte na Porovnat a žádost o přijetí změn a pak vytvořte žádost o přijetí změn.

12. Na stránce žádosti o přijetí změn počkejte na ikonu vedle možnosti Spustit testy Databricks / unit-test-notebook (pull_request), aby se zobrazila zelená značka zaškrtnutí. (Zobrazení ikony může chvíli trvat.) Pokud je místo zelené značky zaškrtnutí červený symbol X, klikněte na Tlačítko Podrobnosti a zjistěte, proč. Pokud se ikona nebo podrobnosti už nezobrazují, klikněte na Zobrazit všechny kontroly.

13. Pokud se zobrazí zelená značka zaškrtnutí, sloučíte žádost o přijetí změn do main větve.

(Volitelné) Krok 7: Aktualizace sdíleného kódu v GitHubu pro aktivaci testů

V tomto kroku provedete změnu sdíleného kódu a pak změny nasdílíte do úložiště GitHub, které okamžitě aktivuje testy automaticky na základě akce GitHubu z předchozího kroku.

Krok 7.1: Vytvoření další pracovní větve v úložišti

1. V prohlížeči pracovního prostoru otevřete složku Git s nejlepšími poznámkovými bloky.
2. Vedle názvu složky klikněte na tlačítko first_tests větev Gitu.
3. V dialogovém okně nejlepších notebooků klikněte na šipku rozevíracího seznamu vedle větve first_tests a vyberte hlavní.
4. Klikněte na tlačítko Vyžádat . Pokud se zobrazí výzva k pokračování stahování, klikněte na Potvrdit.
5. Klikněte na + tlačítko (Vytvořit větev).
6. Zadejte trigger_testsa klikněte na Vytvořit. (Větev můžete pojmenovat jinak.)
7. Zavřete toto dialogové okno.

Krok 7.2: Změna sdíleného kódu

1. V prohlížeči pracovního prostoru klikněte ve složce Git s nejlepšími poznámkovými bloky na soubor covid_analysis/transforms.py.

2. Změňte třetí řádek tohoto souboru:

   # Filter by country code.
   

   Na toto:

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

Krok 7.3: Vrácením změny se změnami aktivujte testy

1. Vedle názvu souboru klikněte na tlačítko trigger_tests větev Gitu.
2. V dialogovém okně nejlepších poznámkových bloků na kartě Změny se ujistěte, že je vybraná covid_analysis/transforms.py.
3. Pro potvrzení zprávy (povinné) zadejte Updated comment.
4. Jako popis (volitelné) zadejte This updates the comment for filter_country.
5. Klikněte na Potvrdit a nasdílení změn.
6. V banneru klikněte na odkaz žádosti o přijetí změn v části Vytvoření žádosti o přijetí změn u svého poskytovatele Gitu a pak vytvořte žádost o přijetí změn na GitHubu.
7. Na stránce žádosti o přijetí změn počkejte na ikonu vedle možnosti Spustit testy Databricks / unit-test-notebook (pull_request), aby se zobrazila zelená značka zaškrtnutí. (Zobrazení ikony může chvíli trvat.) Pokud je místo zelené značky zaškrtnutí červený symbol X, klikněte na Tlačítko Podrobnosti a zjistěte, proč. Pokud se ikona nebo podrobnosti už nezobrazují, klikněte na Zobrazit všechny kontroly.
8. Pokud se zobrazí zelená značka zaškrtnutí, sloučíte žádost o přijetí změn do main větve.