Sdílet prostřednictvím

Osvědčené postupy v softwarovém inženýrství pro práci s notebooky

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řidejte poznámkové bloky do složek Git na 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 Git, 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 názvem úložiště v tomto názorném postupu.) 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 .

  • Víceúčelový cluster Azure Databricks 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 průvodce 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 pro poskytovatele Gitu zadejte své uživatelské jméno na GitHubu.
  6. Jako token zadejte osobní přístupový token GitHubu (classic). Tento osobní přístupový token (classic) musí mít oprávnění pro repo a pro pracovní postup.
  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 >.
  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 URL Clone s použitím 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 poskytovateli Git vyberte GitHub.
    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 to usnadnili, poskytujeme je zde pro vás.

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.)

Poznámka:

V některých úložištích main může být větev pojmenována master. Pokud ano, nahraďte main za master v tomto průvodci.

Návod

Pokud nejste obeznámeni s prací ve větvích Gitu, přečtěte si téma Větve Gitu – Větve ve Zkratce na webu Git.

  1. Složka Git z kroku 1.2 by měla být otevřená. Pokud ne, pak v postranním panelu pracovního prostoru rozbalte uživatelé pracovního prostoru>, poté rozbalte složku se svým uživatelským jménem a klikněte na svou složku Git.

  2. Vedle názvu složky v navigačním pruhu 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 repozitáře do vašeho repozitáře. Tento notebook 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ámcepandas.
  • Filtruje data tak, aby obsahovala metriky pouze z USA.
  • Zobrazí graf dat.
  • Uloží datový rámec pandas jako Pandas API pro Spark DataFrame.
  • 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 Git složcebest-notebooks 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. Pro Importovat z vyberte URL.

    2. Zadejte adresu URL ke zdrojovému obsahu covid_eda_raw notebooku 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 Surový. 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: Spusťte poznámkový blok

  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: Zkontrolovat a sloučit poznámkový blok

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ě best-notebooks na kartě Změny se ujistěte, že je vybraný soubor notebooks/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 odeslat.
  6. V banneru klikněte na odkaz pull requestu v části Vytvoření pull requestu u 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. Vraťte se do pracovního prostoru Azure Databricks a zavřete dialogové okno best-notebooks, 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 Stáhnout. 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. Pro Importovat z vyberte URL.

    2. Zadejte adresu URL ke zdrojovému obsahu covid_eda_modular notebooku 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 Surový. 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

Návod

Pro jiné techniky sdílení kódu viz Databricks: Sdílení kódu mezi poznámkovými bloky.

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ů. Pro lepší kompatibilitu můžete tyto verze porovnat s verzemi, které jsou nainstalované na vašem univerzálním clusteru. Informace o verzi Databricks Runtime vašeho clusteru najdete v části "System environment" v poznámkách k vydání a kompatibilitě 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 covid_eda_modular dílčím kroku spustíte poznámkový blok, který volá sdílený kód v covid_analysis/transforms.py souboru.

  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.

  1. Vedle názvu poznámkového bloku klikněte na větev Gitu first_modules.
  2. V dialogovém okně nejlepších notebooků 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 odeslat.
  6. V banneru klikněte na odkaz pull requestu v části Vytvoření pull requestu u 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. Vraťte se do pracovního prostoru Azure Databricks a zavřete dialogové okno best-notebooks, 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. Ale chcete tento kód otestovat bez spuštění samotného poznámkového bloku covid_eda_modular. 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í.

Návod

Další přístupy k testování poznámkových bloků a také testování poznámkových bloků R a Scala najdete v tématu Testování jednotek pro poznámkové bloky.

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

  1. Vedle názvu poznámkového bloku klikněte na větev Gitu first_modules.
  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 Stáhnout. 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, při ověření tento konkrétní test selže, a proto selže samotný test.

  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í pytesttestovací přípravky a také simulovaný datový rámec pandas v operační 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 testů Pythonu do vašeho pracovního prostoru, spustí testy a ohlásí jejich výsledky. I když můžete spustit pytest z webového terminálu clusteru, spouštění pytest z poznámkového bloku může být pohodlnější.

Poznámka:

Spuštěním pytest se spustí všechny soubory, jejichž názvy odpovídají formátu test_*.py nebo /*_test.py v aktuálním adresáři a jeho podadresářích.

  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. Pro Importovat z vyberte URL.

    2. Zadejte adresu URL ke zdrojovému obsahu run_unit_tests notebooku 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 Surový. 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 ukončení běhu poznámkového bloku by se v poznámkovém bloku měly zobrazit informace o počtu úspěšných a neúspěšných testů 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
  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 notebooků 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 odeslat.
  6. V banneru klikněte na odkaz pull requestu v části Vytvoření pull requestu u 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. Vraťte se do pracovního prostoru Azure Databricks a zavřete dialogové okno best-notebooks, 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. V pracovním prostoru klikněte na ikonu Pracovní postupy.Úlohy a kanály na bočním panelu
  2. Klikněte na Vytvořit a potom na Úlohu.
  3. Upravte název úlohy, která má být covid_report.

Poznámka:

Pokud je uživatelské rozhraní úloh Lakeflowzapnuté, klikněte na dlaždici Poznámkový blok a nakonfigurujte první úkol. Pokud dlaždice Poznámkový blok není dostupná, klikněte na Přidat další typ úkolu a vyhledejte Poznámkový blok.

  1. Jako název úkolu zadejte run_notebook_tests.
  2. V případě potřeby vyberte v rozevírací nabídce Typpoznámkový blok.
  3. U zdrojovéhovyberte poskytovatele Gitu.
  4. Klikněte na Přidat gitový odkaz.
  5. V dialogovém okně s informacemi o Gitu:
    1. Jako adresu URL úložiště Git zadejte URL Clone s použitím 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 poskytovateli Git vyberte GitHub.
    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.
  6. Pro Path zadejte notebooks/run_unit_tests. Nepřidávejte příponu .py souboru.
  7. V clusteruvyberte cluster z předchozího kroku.
  8. Klikněte na Vytvořit úkol.

Poznámka:

V tomto scénáři databricks nedoporučuje používat tlačítko plánu v poznámkovém bloku, jak je popsáno v tématu Vytvoření a správa naplánovaných úloh poznámkového bloku k naplánování úlohy, která bude tento poznámkový blok spouštět pravidelně. Důvodem je, že tlačítko plánování vytvoří úlohu pomocí nejnovější pracovní kopie notebooku v úložišti pracovního prostoru. Místo toho Databricks doporučuje, abyste podle předchozích pokynů vytvořili úlohu, která používá nejnovější potvrzenou verzi poznámkového bloku v úložišti.

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 vyskakovací nabídka. Vyberte poznámkový blok.
  3. Jako název úkolu zadejte run_main_notebook.
  4. Pro typvyberte Notebook .
  5. Pro Path zadejte notebooks/covid_eda_modular. Nepřidávejte příponu .py souboru.
  6. V clusteruvyberte cluster z předchozího kroku.
  7. Ověřte, zda hodnota pole Depends on je 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 průběh.

    Poznámka:

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

    1. Na bočním panelu v prostředí Data Science &Engineering nebo Databricks Mosaic AI klikněte na Úlohy a kanály.
    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.

Poznámka:

Tato úloha běžela na vyžádání. Pokud chcete tuto úlohu nastavit tak, aby se spouštěla pravidelně, přečtěte si téma Automatizace úloh s plány a aktivačními událostmi.

(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 aplikačnímu objektu Microsoft Entra ID. Pro pokyny se podívejte do části Azure na stránce GitHubu pro akci Run Databricks Notebook v GitHub Actions Marketplace.

Důležité

Poznámkové bloky se spouštějí se všemi oprávněními pracovního prostoru identity, která je přidružená k tokenu, takže Databricks doporučuje používat služebního principála. Pokud opravdu chcete dát uživateli pracovního prostoru Azure Databricks osobní přístupový token GitHubu pouze pro účely osobního zkoumání a rozumíte tomu, že z bezpečnostních důvodů Databricks tento postup nedoporučuje, podívejte se na pokyny k vytvoření osobního přístupového tokenu uživatele vašeho pracovního prostoru.

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ž je v úložišti vytvořena žá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 webových stránkách úložiště GitHub klikněte na záložku 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 'main'.

  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 hook z GitHub akce Spuštění poznámkového bloku Databricks ke spuštění poznámkového run_unit_tests bloku.

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

    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 do pole Zpráva potvrzení.

  10. Vyberte Přímo zapsat do větve adding_github_actions a klikněte na Zapsat změny.

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

  12. Na stránce žádosti o přijetí změn počkejte, až se vedle Spustit testy Databricks před sloučením / unit-test-notebook (pull_request) zobrazí 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 pull request 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 Git složku best-notebooks.
  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 Stáhnout. 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. Z prohlížeče Workspace, v Git složce best-notebooks, klikněte 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: Zkontrolujte změnu, aby se spustily testy

  1. Vedle názvu souboru klikněte na větev Gitu trigger_tests.
  2. V dialogovém okně best-notebooks na kartě Změny se ujistěte, že je vybrán soubor 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 odeslat.
  6. V banneru klikněte na odkaz "pull request" v sekci Vytvoření pull requestu u svého poskytovatele Gitu a poté vytvořte pull request na GitHubu.
  7. Na stránce žádosti o přijetí změn počkejte, až se vedle Spustit testy Databricks před sloučením / unit-test-notebook (pull_request) zobrazí 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 pull request do main větve.
  • Last updated on