Udostępnij za pośrednictwem

Najlepsze rozwiązania dotyczące inżynierii oprogramowania dla notesów

  • Artykuł

Ten artykuł zawiera praktyczny przewodnik, który pokazuje, jak zastosować najlepsze rozwiązania w zakresie inżynierii oprogramowania do notesów usługi Azure Databricks, w tym kontroli wersji, udostępniania kodu, testowania i opcjonalnie ciągłej integracji i ciągłego wdrażania (CI/CD).

Korzystając z tego przewodnika, wykonasz następujące czynności:

  • Dodaj notesy do folderów Git usługi Azure Databricks na potrzeby kontroli wersji.
  • Wyodrębnij fragmenty kodu z jednego z notesów do modułu z możliwością udostępniania.
  • Przetestuj kod udostępniony.
  • Uruchom notesy z zadania usługi Azure Databricks.
  • Opcjonalnie zastosuj ciągłą integrację/ciągłe wdrażanie do udostępnionego kodu.

Wymagania

Aby ukończyć ten przewodnik, należy podać następujące zasoby:

  • Repozytorium zdalne z dostawcą usługi Git obsługiwanego przez usługę Databricks. W tym artykule przedstawiono sposób użycia usługi GitHub. W tym przewodniku założono, że masz dostępne repozytorium best-notebooks GitHub. (Możesz nadać repozytorium inną nazwę. W takim przypadku zastąp best-notebooks ciąg nazwą repozytorium w tym przewodniku). Utwórz repozytorium GitHub, jeśli jeszcze go nie masz.

    Uwaga

    Jeśli tworzysz nowe repozytorium, pamiętaj o zainicjowaniu repozytorium z co najmniej jednym plikiem README , na przykład pliku.

  • Obszar roboczy usługi Azure Databricks. Utwórz obszar roboczy , jeśli jeszcze go nie masz.

  • Klaster usługi Azure Databricks ogólnego przeznaczenia w obszarze roboczym. Aby uruchamiać notesy w fazie projektowania, należy dołączyć notesy do uruchomionego klastra ogólnego przeznaczenia. W dalszej części tego przewodnika użyto zadania usługi Azure Databricks w celu zautomatyzowania uruchamiania notesów w tym klastrze. (Można również uruchamiać zadania w klastrach zadań, które istnieją tylko dla okresów istnienia zadań). Utwórz klaster all-purpose, jeśli jeszcze go nie masz.

Krok 1. Konfigurowanie folderów Git usługi Databricks

W tym kroku połączysz istniejące repozytorium GitHub z folderami Git usługi Azure Databricks w istniejącym obszarze roboczym usługi Azure Databricks.

Aby umożliwić obszarowi roboczemu łączenie się z repozytorium GitHub, musisz najpierw podać swój obszar roboczy przy użyciu poświadczeń usługi GitHub, jeśli jeszcze tego nie zrobiono.

Krok 1.1. Podanie poświadczeń usługi GitHub

  1. Kliknij swoją nazwę użytkownika w prawym górnym rogu obszaru roboczego, a następnie kliknij pozycję Ustawienia na liście rozwijanej.
  2. Na pasku bocznym Ustawienia w obszarze Użytkownik kliknij pozycję Połączone konta.
  3. W obszarze integracji z Git, dla dostawcy Git , wybierz GitHub .
  4. Kliknij pozycję Osobisty token dostępu.
  5. W polu Nazwa użytkownika lub adres e-mail dostawcy usługi Git wprowadź nazwę użytkownika usługi GitHub.
  6. W polu Token wprowadź osobisty token dostępu w usłudze GitHub (wersja klasyczna). Ten osobisty token dostępu (klasyczny) musi mieć uprawnienia repozytorium i przepływu pracy .
  7. Kliknij przycisk Zapisz.

Krok 1.2. Nawiązywanie połączenia z repozytorium GitHub

  1. Na pasku bocznym obszaru roboczego kliknij pozycję Obszar roboczy.
  2. W przeglądarce Obszar roboczy rozwiń węzeł > obszaru roboczego.
  3. Kliknij prawym przyciskiem myszy folder nazwy użytkownika, a następnie kliknij polecenie Utwórz > folder Git.
  4. W oknie dialogowym Tworzenie folderu Git:
    1. W polu Adres URL repozytorium Git wprowadź ciąg GitHub Clone with HTTPS URL for your GitHub repo (Klon usługi GitHub przy użyciu adresu URL protokołu HTTPS ). W tym artykule założono, że adres URL kończy się na best-notebooks.git, na przykład https://github.com/<your-GitHub-username>/best-notebooks.git.
    2. W przypadku dostawcy Gitwybierz GitHub.
    3. Pozostaw nazwę folderu Git zgodną z nazwą repozytorium, na przykład best-notebooks.
    4. Kliknij pozycję Utwórz folder Git.

Krok 2. Importowanie i uruchamianie notesu

W tym kroku zaimportujesz istniejący notes zewnętrzny do repozytorium. Możesz utworzyć własne notesy na potrzeby tego przewodnika, ale aby przyspieszyć działanie tych notesów, udostępniamy je tutaj.

Krok 2.1. Tworzenie gałęzi roboczej w repozytorium

W tym podkroku utworzysz gałąź o nazwie eda w repozytorium. Ta gałąź umożliwia pracę nad plikami i kodem niezależnie od gałęzi repozytorium main , która jest najlepszym rozwiązaniem w zakresie inżynierii oprogramowania. (Możesz nadać gałęzi inną nazwę).

Uwaga

W niektórych repozytoriach main gałąź może mieć nazwę master zamiast tego. Jeśli tak, zastąp ciąg main ciągiem master w tym przewodniku.

Napiwek

Jeśli nie znasz pracy w gałęziach usługi Git, zobacz Git Branches — Branches in a Nutshell (Gałęzie usługi Git — Gałęzie w programie Nutshell ) w witrynie internetowej Git.

  1. Folder Git z kroku 1.2 powinien być otwarty. Jeśli nie, na pasku bocznym Obszar roboczy rozwiń węzeł Użytkownicy obszaru roboczego>, a następnie rozwiń folder nazwy użytkownika i kliknij folder Git.

  2. Obok nazwy folderu w obszarze nawigacji obszaru roboczego kliknij przycisk głównej gałęzi Git.

  3. W oknie dialogowym Najlepsze notesy kliknij przycisk Utwórz gałąź.

    Uwaga

    Jeśli repozytorium ma nazwę inną niż best-notebooks, tytuł tego okna dialogowego będzie inny, tutaj i w tym przewodniku.

  4. Wprowadź edaciąg , a następnie kliknij przycisk Utwórz.

  5. Zamknij to okno dialogowe.

Krok 2.2. Importowanie notesu do repozytorium

W tym podstepie zaimportujesz istniejący notes z innego repozytorium do repozytorium. Ten notes wykonuje następujące czynności:

Chociaż możesz utworzyć własny notes w repozytorium tutaj, importowanie istniejącego notesu pomaga przyspieszyć ten przewodnik. Aby utworzyć notes w tej gałęzi lub przenieść istniejący notes do tej gałęzi zamiast importować notes, zobacz Podstawowe użycie plików obszaru roboczego.

  1. W folderze Git best-notebooks kliknij pozycję Utwórz > folder.
  2. W oknie dialogowym Nowy folder wprowadź ciąg notebooks, a następnie kliknij przycisk Utwórz.
  3. W folderze notebooks kliknij kebab, a następnie pozycję Importuj.
  4. W oknie dialogowym Importowanie:

    1. W przypadku Importuj z, wybierz adres URL.

    2. Wprowadź adres URL nieprzetworzonej zawartości notesu covid_eda_raw w databricks/notebook-best-practices repozytorium w usłudze GitHub. Aby uzyskać ten adres URL: i. Przejdź do https://github.com/databricks/notebook-best-practices. ii. notebooks Kliknij folder. iii. covid_eda_raw.py Kliknij plik. iv. Kliknij pozycję Nieprzetworzone. v. Skopiuj pełny adres URL z paska adresu przeglądarki internetowej do okna dialogowego Importowanie .

      Uwaga

      Okno dialogowe Importowanie działa tylko z adresami URL usługi Git dla repozytoriów publicznych.

    3. Kliknij przycisk Importuj.

Krok 2.3. Uruchamianie notesu

  1. Jeśli notes nie jest jeszcze wyświetlany, otwórz folder notesów , a następnie kliknij notes covid_eda_raw wewnątrz folderu.
  2. Wybierz klaster, aby połączyć ten notes z. Aby uzyskać instrukcje dotyczące tworzenia klastra, zobacz Tworzenie klastra.
  3. Kliknij pozycję Uruchom wszystko.
  4. Zaczekaj na uruchomienie notesu.

Po zakończeniu działania notatnika powinien być wyświetlony wykres danych oraz ponad 600 wierszy surowych danych w tabeli Delta. Jeśli klaster nie był jeszcze uruchomiony podczas uruchamiania tego notesu, uruchomienie klastra może potrwać kilka minut przed wyświetleniem wyników.

Krok 2.4. Zaewidencjonuj i scal notes

W tym podkroku zapiszesz swoją pracę do tej pory w repozytorium GitHub. Następnie scalisz notes z gałęzi roboczej z gałęzią repozytorium main .

  1. Obok nazwy notesu kliknij przycisk gałęzi eda Git.
  2. W oknie dialogowym Najlepsze notesy na karcie Zmiany upewnij się, że wybrano plik notebooks/covid_eda_raw.py.
  3. W polu Komunikat zatwierdzenia (wymagany) wprowadź wartość Added raw notebook.
  4. W polu Opis (opcjonalnie)wprowadź This is the first version of the notebook.
  5. Kliknij pozycję Zatwierdź i wypchnij.
  6. Kliknij link żądanie ściągnięcia w obszarze Tworzenie żądania ściągnięcia u dostawcy git na banerze.
  7. W usłudze GitHub utwórz żądanie ściągnięcia, a następnie scal żądanie ściągnięcia z gałęzią main .
  8. Po powrocie do obszaru roboczego usługi Azure Databricks zamknij okno dialogowe najlepsze notesy , jeśli nadal jest wyświetlane.

Krok 3. Przenoszenie kodu do udostępnionego modułu

W tym kroku przeniesiesz część kodu w notesie do zestawu funkcji udostępnionych poza notesem. Dzięki temu można używać tych funkcji z innymi podobnymi notesami, co może przyspieszyć przyszłe kodowanie i zapewnić bardziej przewidywalne i spójne wyniki notesu. Udostępnianie tego kodu umożliwia również łatwiejsze testowanie tych funkcji, które jako najlepsze rozwiązanie w zakresie inżynierii oprogramowania może podnieść ogólną jakość kodu podczas pracy.

Krok 3.1. Tworzenie innej gałęzi roboczej w repozytorium

  1. Obok nazwy notesu kliknij przycisk gałęzi eda Git.
  2. W oknie dialogowym najlepszych notatników kliknij strzałkę listy rozwijanej obok gałęzi i wybierz główną.
  3. Kliknij przycisk Pull (Ściąganie). Jeśli zostanie wyświetlony monit o kontynuowanie ściągania, kliknij przycisk Potwierdź.
  4. Kliknij przycisk Utwórz gałąź.
  5. Wprowadź ciąg first_modules, a następnie kliknij przycisk Utwórz. (Możesz nadać gałęzi inną nazwę).
  6. Zamknij to okno dialogowe.

Krok 3.2. Importowanie notesu do repozytorium

Aby przyspieszyć ten przewodnik, w tym podkroku zaimportujesz inny istniejący notes do repozytorium. Ten notes wykonuje te same czynności co poprzedni notes, z tą różnicą, że ten notes będzie wywoływać funkcje kodu udostępnionego przechowywane poza notesem. Ponownie możesz utworzyć własny notes w repozytorium tutaj i wykonać rzeczywiste udostępnianie kodu samodzielnie.

  1. W przeglądarce Obszar roboczy kliknij prawym przyciskiem myszy folder notesów , a następnie kliknij polecenie Importuj.
  2. W oknie dialogowym Importowanie:

    1. Dla Importuj zwybierz adres URL.

    2. Wprowadź adres URL nieprzetworzonej zawartości notesu covid_eda_modular w databricks/notebook-best-practices repozytorium w usłudze GitHub. Aby uzyskać ten adres URL: i. Przejdź do https://github.com/databricks/notebook-best-practices. ii. notebooks Kliknij folder. iii. covid_eda_modular.py Kliknij plik. iv. Kliknij pozycję Nieprzetworzone. v. Skopiuj pełny adres URL z paska adresu przeglądarki internetowej do okna dialogowego Importowanie notesów .

      Uwaga

      Okno dialogowe Importowanie notesów działa tylko z adresami URL usługi Git dla repozytoriów publicznych.

    3. Kliknij przycisk Importuj.

Krok 3.3. Dodawanie pomocniczych funkcji kodu udostępnionego notesu

  1. W przeglądarce Obszar roboczy kliknij prawym przyciskiem myszy folder Git best-notebooks , a następnie kliknij polecenie Utwórz > folder.

  2. W oknie dialogowym Nowy folder wprowadź ciąg covid_analysis, a następnie kliknij przycisk Utwórz.

  3. W folderze covid_analysis kliknij pozycję Utwórz > plik.

  4. W oknie dialogowym Nowa nazwa pliku wprowadź ciąg transforms.py, a następnie kliknij pozycję Utwórz plik.

  5. W oknie edytora transforms.py wprowadź następujący kod:

    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

Napiwek

Aby zapoznać się z innymi technikami udostępniania kodu, zobacz Udostępnianie kodu między notesami usługi Databricks.

Krok 3.4. Dodawanie zależności kodu udostępnionego

Powyższy kod ma kilka zależności pakietów języka Python, aby umożliwić prawidłowe uruchamianie kodu. W tym podkroku deklarujesz te zależności pakietu. Deklarowanie zależności zwiększa powtarzalność przy użyciu dokładnie zdefiniowanych wersji bibliotek.

  1. W przeglądarce Obszar roboczy kliknij prawym przyciskiem myszy folder Git best-notebooks , a następnie kliknij polecenie Utwórz > plik.

    Uwaga

    Chcesz, aby plik zawierający listę zależności pakietów przechodził do katalogu głównego folderu Git, a nie do notesów lub folderów covid_analysis .

  2. W oknie dialogowym Nowa nazwa pliku wprowadź ciąg requirements.txt, a następnie kliknij pozycję Utwórz plik.

  3. W oknie edytora requirements.txt wprowadź następujący kod:

    Uwaga

    Jeśli plik requirements.txt nie jest widoczny, może być konieczne odświeżenie przeglądarki internetowej.

    -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

    Uwaga

    Powyższy plik zawiera listę określonych wersji pakietów. Aby uzyskać lepszą zgodność, można odwoływać się do tych wersji z tymi, które są zainstalowane w klastrze all-purpose. Zobacz sekcję "Środowisko systemowe" dla wersji środowiska Databricks Runtime klastra w artykule Databricks Runtime release notes versions and compatibility (Wersje i zgodność środowiska Uruchomieniowego usługi Databricks Runtime).

Struktura repozytorium powinna teraz wyglądać następująco:

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

Krok 3.5. Uruchamianie refaktoryzowanego notesu

W tym podstepie uruchomisz covid_eda_modular notes, który wywołuje udostępniony kod w pliku covid_analysis/transforms.py.

  1. W przeglądarce Obszar roboczy kliknij notes covid_eda_modular w folderze notesy .
  2. Wybierz klaster, aby dołączyć ten notebook do.
  3. Kliknij pozycję Uruchom wszystko.
  4. Zaczekaj na uruchomienie notesu.

Po zakończeniu działania notesu w notesie powinny zostać wyświetlone podobne wyniki jak notes covid_eda_raw: wykres danych, a także ponad 600 wierszy danych pierwotnych w tabeli delty. Główną różnicą w tym notesie jest użycie innego filtru ( iso_codeDZA zamiast USA). Jeśli klaster nie był jeszcze uruchomiony podczas uruchamiania tego notesu, uruchomienie klastra może potrwać kilka minut przed wyświetleniem wyników.

  1. Obok nazwy notesu kliknij przycisk first_modules gałęzi Git.
  2. W oknie dialogowym Najlepsze notesy na karcie Zmiany upewnij się, że wybrano następujące opcje:
    • requirements.txt
    • covid_analysis/transforms.py
    • notesy/covid_eda_modular.py
  3. W polu Komunikat zatwierdzenia (wymagany) wprowadź wartość Added refactored notebook.
  4. W polu Opis (opcjonalnie)wprowadź This is the second version of the notebook.
  5. Kliknij pozycję Zatwierdź i wypchnij.
  6. Kliknij link żądanie ściągnięcia w obszarze Tworzenie żądania ściągnięcia u dostawcy git na banerze.
  7. W usłudze GitHub utwórz żądanie ściągnięcia, a następnie scal żądanie ściągnięcia z gałęzią main .
  8. Po powrocie do obszaru roboczego usługi Azure Databricks zamknij okno dialogowe najlepsze notesy , jeśli nadal jest wyświetlane.

Krok 4. Testowanie udostępnionego kodu

W tym kroku przetestujesz kod udostępniony z ostatniego kroku. Jednak chcesz przetestować ten kod bez uruchamiania samego notesu covid_eda_modular . Jest to spowodowane tym, że jeśli nie można uruchomić kodu udostępnionego, sam notes prawdopodobnie również nie powiedzie się. Chcesz przechwycić błędy w kodzie udostępnionym, zanim główny notes w końcu nie powiedzie się później. Ta technika testowania to najlepsze rozwiązanie w zakresie inżynierii oprogramowania.

Napiwek

Aby uzyskać dodatkowe podejścia do testowania notesów, a także testowania notesów języka R i Scala, zobacz Testowanie jednostkowe notesów.

Krok 4.1. Tworzenie innej gałęzi roboczej w repozytorium

  1. Obok nazwy notesu kliknij przycisk first_modules gałęzi Git.
  2. W oknie dialogowym best-notebooks kliknij strzałkę listy rozwijanej obok gałęzi first_modules i wybierz main.
  3. Kliknij przycisk Pull (Ściąganie). Jeśli zostanie wyświetlony monit o kontynuowanie ściągania, kliknij przycisk Potwierdź.
  4. Kliknij pozycję Utwórz gałąź.
  5. Wprowadź ciąg first_tests, a następnie kliknij przycisk Utwórz. (Możesz nadać gałęzi inną nazwę).
  6. Zamknij to okno dialogowe.

Krok 4.2. Dodawanie testów

W tym podkroku użyjesz struktury pytest do przetestowania udostępnionego kodu. W tych testach stwierdzasz, czy określone wyniki testów są osiągane. Jeśli jakikolwiek test generuje nieoczekiwany wynik, ten konkretny test zakończy się niepowodzeniem asercji, a tym samym sam test zakończy się niepowodzeniem.

  1. W przeglądarce Obszar roboczy kliknij prawym przyciskiem myszy folder Git, a następnie kliknij polecenie Utwórz > folder.

  2. W oknie dialogowym Nowy folder wprowadź ciąg tests, a następnie kliknij przycisk Utwórz.

  3. W folderze tests kliknij pozycję Utwórz > plik.

  4. W oknie dialogowym Nowa nazwa pliku wprowadź ciąg testdata.csv, a następnie kliknij pozycję Utwórz plik.

  5. W oknie edytora testdata.csv wprowadź następujące dane testowe:

    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. W folderze tests kliknij pozycję Utwórz > plik.

  7. W oknie dialogowym Nowa nazwa pliku wprowadź ciąg transforms_test.py, a następnie kliknij pozycję Utwórz plik.

  8. W oknie edytora transforms_test.py wprowadź następujący kod testowy. Te testy używają standardowych pytesturządzeń , a także wyśmiewane w pamięci ramki danych pandas:

    # 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 repozytorium powinna teraz wyglądać następująco:

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

Krok 4.3. Uruchamianie testów

Aby przyspieszyć ten przewodnik, w tym podkroku użyjesz zaimportowanego notesu do uruchomienia poprzednich testów. Ten notes pobiera i instaluje zależne pakiety języka Python testów do obszaru roboczego, uruchamia testy i raportuje wyniki testów. Chociaż można uruchomić polecenie pytest z poziomu terminalu internetowego klastra, uruchomienie pytest z notesu może być wygodniejsze.

Uwaga

Uruchamianie pytest uruchamia wszystkie pliki, których nazwy są zgodne z formularzem test_*.py lub /*_test.py w bieżącym katalogu i jego podkatalogach.

  1. W przeglądarce Obszar roboczy kliknij prawym przyciskiem myszy folder notesów , a następnie kliknij polecenie Importuj.
  2. W oknie dialogowym Importowanie notesów:

    1. Dla Importuj z, wybierz adres URL.

    2. Wprowadź adres URL nieprzetworzonej zawartości notesu run_unit_tests w databricks/notebook-best-practices repozytorium w usłudze GitHub. Aby uzyskać ten adres URL: i. Przejdź do https://github.com/databricks/notebook-best-practices. ii. notebooks Kliknij folder. iii. run_unit_tests.py Kliknij plik. iv. Kliknij pozycję Nieprzetworzone. v. Skopiuj pełny adres URL z paska adresu przeglądarki internetowej do okna dialogowego Importowanie notesów .

      Uwaga

      Okno dialogowe Importowanie notesów działa tylko z adresami URL usługi Git dla repozytoriów publicznych.

    3. Kliknij przycisk Importuj.

  3. Wybierz klaster, aby dołączyć ten notatnik do.
  4. Kliknij pozycję Uruchom wszystko.
  5. Zaczekaj na uruchomienie notesu.

Po zakończeniu działania notesu w notesie powinny zostać wyświetlone informacje o liczbie testów zakończonych powodzeniem i niepowodzeniem wraz z innymi powiązanymi szczegółami. Jeśli klaster nie był jeszcze uruchomiony podczas uruchamiania tego notesu, uruchomienie klastra może potrwać kilka minut przed wyświetleniem wyników.

Struktura repozytorium powinna teraz wyglądać następująco:

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  ├── covid_eda_raw (optional)
│  └── run_unit_tests
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py
  1. Obok nazwy notesu kliknij przycisk first_tests gałęzi Git.
  2. W oknie dialogowym Najlepsze notesy na karcie Zmiany upewnij się, że wybrano następujące opcje:
    • testy/transforms_test.py
    • notesy/run_unit_tests.py
    • testy/testdata.csv
  3. W polu Komunikat zatwierdzenia (wymagany) wprowadź wartość Added tests.
  4. W polu Opis (opcjonalnie)wprowadź wartość These are the unit tests for the shared code..
  5. Kliknij pozycję Zatwierdź i wypchnij.
  6. Kliknij link żądanie ściągnięcia w obszarze Tworzenie żądania ściągnięcia u dostawcy git na banerze.
  7. W usłudze GitHub utwórz żądanie ściągnięcia, a następnie scal żądanie ściągnięcia z gałęzią main .
  8. Po powrocie do obszaru roboczego usługi Azure Databricks zamknij okno dialogowe najlepsze notesy , jeśli nadal jest wyświetlane.

Krok 5. Tworzenie zadania do uruchamiania notesów

W poprzednich krokach ręcznie przetestowano udostępniony kod i ręcznie uruchomiono notesy. W tym kroku użyjesz zadania usługi Azure Databricks, aby przetestować udostępniony kod i uruchomić notesy automatycznie, na żądanie lub zgodnie z regularnym harmonogramem.

Krok 5.1. Tworzenie zadania podrzędnego w celu uruchomienia notesu testowania

  1. Na pasku bocznym obszaru roboczego kliknij pozycję Przepływy pracy.
  2. Na karcie Zadania kliknij pozycję Utwórz zadanie.
  3. Edytuj nazwę zadania, aby mieć wartość covid_report.
  4. W polu Nazwa zadania wprowadź .run_notebook_tests
  5. Dla Typewybierz Notebook.
  6. Dla źródła, wybierz dostawcę Git .
  7. Kliknij pozycję Dodaj odwołanie do usługi Git.
  8. W oknie dialogowym Informacje o usłudze Git:
    1. W polu Adres URL repozytorium Git wprowadź ciąg GitHub Clone with HTTPS URL for your GitHub repo (Klon usługi GitHub przy użyciu adresu URL protokołu HTTPS ). W tym artykule założono, że adres URL kończy się na best-notebooks.git, na przykład https://github.com/<your-GitHub-username>/best-notebooks.git.
    2. W przypadku dostawcy usługi Gitwybierz pozycję GitHub.
    3. W polu Dokumentacja usługi Git (gałąź/tag/zatwierdzenie), wprowadź .main
    4. Obok odniesienia Git (gałąź/tag/zatwierdzenie)wybierz gałąź.
    5. Kliknij przycisk Potwierdź.
  9. W polu Ścieżka wprowadź wartość notebooks/run_unit_tests. Nie należy dodawać .py rozszerzenia pliku.
  10. W przypadku Clusterwybierz klaster z poprzedniego kroku.
  11. Kliknij pozycję Utwórz zadanie.

Uwaga

W tym scenariuszu usługa Databricks nie zaleca używania przycisku harmonogramu w notesie zgodnie z opisem w temacie Tworzenie zaplanowanych zadań notesu i zarządzanie nimi w celu okresowego planowania zadania uruchamiania tego notesu. Dzieje się tak, ponieważ przycisk harmonogramu tworzy zadanie przy użyciu najnowszej kopii roboczej notesu w repozytorium obszaru roboczego. Zamiast tego usługa Databricks zaleca wykonanie powyższych instrukcji w celu utworzenia zadania, które używa najnowszej zatwierdzonej wersji notesu w repozytorium.

Krok 5.2. Tworzenie zadania podrzędnego w celu uruchomienia notesu głównego

  1. Kliknij ikonę + Dodaj zadanie .
  2. Zostanie wyświetlone menu podręczne. Wybierz pozycję Notebook.
  3. W polu Nazwa zadania wprowadź .run_main_notebook
  4. Dla Typewybierz Notebook.
  5. W polu Ścieżka wprowadź wartość notebooks/covid_eda_modular. Nie należy dodawać .py rozszerzenia pliku.
  6. W przypadku Clusterwybierz klaster z poprzedniego kroku.
  7. Sprawdź, czy wartość zależy od wartości to run_notebook-tests.
  8. Kliknij pozycję Utwórz zadanie.

Krok 5.3. Uruchamianie zadania

  1. Kliknij przycisk Uruchom teraz.

  2. W wyskakującym okienku kliknij pozycję Widok uruchom.

    Uwaga

    Jeśli wyskakujące okienko znika zbyt szybko, wykonaj następujące czynności:

    1. Na pasku bocznym w środowisku Nauka o danych & Engineering lub Databricks Mosaic AI kliknij pozycję Przepływy pracy.
    2. Na karcie Zadanie jest uruchamiane kliknij wartość Godzina rozpoczęcia dla najnowszego zadania z covid_report w kolumnie Zadania.

  3. Aby wyświetlić wyniki zadania, kliknij kafelek run_notebook_tests , kafelek run_main_notebook lub oba te elementy. Wyniki na każdym kafelku są takie same, jak w przypadku samodzielnego uruchomienia notesów.

Uwaga

To zadanie zostało uruchomione na żądanie. Aby skonfigurować to zadanie do regularnego uruchamiania, zobacz Automatyzowanie zadań za pomocą harmonogramów i wyzwalaczy.

(Opcjonalnie) Krok 6. Konfigurowanie repozytorium w celu przetestowania kodu i automatycznego uruchamiania notesu za każdym razem, gdy kod ulegnie zmianie

W poprzednim kroku użyto zadania do automatycznego testowania udostępnionego kodu i uruchamiania notesów w danym momencie lub cyklicznie. Jednak wolisz automatycznie wyzwalać testy po scaleniu zmian z repozytorium GitHub przy użyciu narzędzia ciągłej integracji/ciągłego wdrażania, takiego jak GitHub Actions.

Krok 6.1. Konfigurowanie dostępu usługi GitHub do obszaru roboczego

W tym podkroku skonfigurujesz przepływ pracy funkcji GitHub Actions, który uruchamia zadania w obszarze roboczym, gdy tylko zmiany zostaną scalone do repozytorium. W tym celu należy nadać usłudze GitHub unikatowy token usługi Azure Databricks na potrzeby dostępu.

Ze względów bezpieczeństwa usługa Databricks zniechęca cię do podawania osobistego tokenu dostępu użytkownika obszaru roboczego usługi Azure Databricks do usługi GitHub. Zamiast tego usługa Databricks zaleca nadanie usłudze GitHub tokenu identyfikatora Entra firmy Microsoft skojarzonego z jednostką usługi Microsoft Entra ID. Aby uzyskać instrukcje, zobacz sekcję platformy Azure na stronie Uruchamianie akcji github notesu usługi Databricks w witrynie Marketplace funkcji GitHub Actions.

Ważne

Notesy są uruchamiane ze wszystkimi uprawnieniami obszaru roboczego tożsamości skojarzonej z tokenem, dlatego usługa Databricks zaleca użycie jednostki usługi. Jeśli naprawdę chcesz nadać osobisty token dostępu użytkownika obszaru roboczego usługi Azure Databricks do usługi GitHub tylko do celów osobistych eksploracji i rozumiesz, że ze względów bezpieczeństwa usługa Databricks zniechęca do tego rozwiązania, zapoznaj się z instrukcjami dotyczącymi tworzenia osobistego tokenu dostępu użytkownika obszaru roboczego.

Krok 6.2. Dodawanie przepływu pracy funkcji GitHub Actions

W tym podkroku dodasz przepływ pracy funkcji GitHub Actions, aby uruchomić run_unit_tests notes za każdym razem, gdy istnieje żądanie ściągnięcia do repozytorium.

Ten podstep przechowuje przepływ pracy funkcji GitHub Actions w pliku przechowywanym na wielu poziomach folderów w repozytorium GitHub. Funkcja GitHub Actions wymaga, aby w repozytorium istniała określona hierarchia folderów zagnieżdżonych w celu prawidłowego działania. Aby wykonać ten krok, musisz użyć witryny internetowej dla repozytorium GitHub, ponieważ interfejs użytkownika folderu usługi Git usługi Azure Databricks nie obsługuje tworzenia hierarchii folderów zagnieżdżonych.

  1. W witrynie internetowej repozytorium GitHub kliknij kartę Kod .

  2. Kliknij strzałkę obok główny, aby rozwinąć listę rozwijaną Przełączanie gałęzi lub tagów.

  3. W polu Znajdź lub utwórz gałąź wprowadź .adding_github_actions

  4. Kliknij pozycję Utwórz gałąź: adding_github_actions z gałęzi "main".

  5. Kliknij pozycję Dodaj plik > Utwórz nowy plik.

  6. W polu Nazwa pliku wprowadź wartość .github/workflows/databricks_pull_request_tests.yml.

  7. W oknie edytora wprowadź następujący kod. Ten kod używa elementu zaczepienia pull_request z akcji GitHub Uruchom notes usługi Databricks w celu uruchomienia notesu run_unit_tests .

    W poniższym kodzie zastąp:

    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. Kliknij pozycję Zatwierdź zmiany.

  9. W oknie dialogowym Zatwierdzanie zmian wprowadź Create databricks_pull_request_tests.yml komunikat Commit (Zatwierdzanie)

  10. Wybierz , aby bezpośrednio zatwierdzić do gałęzi adding_github_actions, a następnie kliknij Zatwierdź zmiany.

  11. Na karcie Kod kliknij pozycję Porównaj i żądanie ściągnięcia, a następnie utwórz żądanie ściągnięcia.

  12. Na stronie żądania ściągnięcia poczekaj na ikonę obok pozycji Uruchom testy usługi Databricks wstępnie scalane / unit-test-notebook (pull_request), aby wyświetlić zielony znacznik wyboru. (Wyświetlenie ikony może potrwać kilka minut). Jeśli jest czerwony znak X zamiast zielonego znacznika wyboru, kliknij pozycję Szczegóły , aby dowiedzieć się, dlaczego. Jeśli ikona lub Szczegóły nie są już wyświetlane, kliknij przycisk Pokaż wszystkie testy.

  13. Jeśli zostanie wyświetlony zielony znacznik wyboru, scal żądanie ściągnięcia z gałęzią main .

(Opcjonalnie) Krok 7. Aktualizowanie kodu udostępnionego w usłudze GitHub w celu wyzwalania testów

W tym kroku wprowadzisz zmianę w kodzie udostępnionym, a następnie wypchniesz zmianę do repozytorium GitHub, które natychmiast wyzwala testy automatycznie na podstawie akcji usługi GitHub z poprzedniego kroku.

Krok 7.1. Tworzenie innej gałęzi roboczej w repozytorium

  1. W przeglądarce Obszar roboczy otwórz folder Git best-notebooks .
  2. Obok nazwy folderu kliknij przycisk first_tests gałęzi Git.
  3. W oknie dialogowym best-notebooks kliknij strzałkę obok gałęzi first_tests i wybierz main.
  4. Kliknij przycisk Pull (Ściąganie). Jeśli zostanie wyświetlony monit o kontynuowanie ściągania, kliknij przycisk Potwierdź.
  5. + Kliknij przycisk (Utwórz gałąź).
  6. Wprowadź ciąg trigger_tests, a następnie kliknij przycisk Utwórz. (Możesz nadać gałęzi inną nazwę).
  7. Zamknij to okno dialogowe.

Krok 7.2. Zmiana udostępnionego kodu

  1. W przeglądarce Obszar roboczy w folderze Git best-notebooks kliknij plik covid_analysis/transforms.py .

  2. Zmień trzeci wiersz tego pliku:

    # Filter by country code.

    Do tego:

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

Krok 7.3. Zaewidencjonuj zmianę, aby wyzwolić testy

  1. Obok nazwy pliku kliknij przycisk trigger_tests gałęzi Git.
  2. W oknie dialogowym Najlepsze notesy na karcie Zmiany upewnij się, że wybrano covid_analysis/transforms.py.
  3. W polu Komunikat zatwierdzenia (wymagany) wprowadź wartość Updated comment.
  4. W polu Opis (opcjonalnie)wprowadź This updates the comment for filter_country.
  5. Kliknij pozycję Zatwierdź i wypchnij.
  6. Kliknij link żądanie ściągnięcia w obszarze Tworzenie żądania ściągnięcia u dostawcy git na banerze, a następnie utwórz żądanie ściągnięcia w usłudze GitHub.
  7. Na stronie żądania ściągnięcia poczekaj na ikonę obok pozycji Uruchom testy usługi Databricks wstępnie scalane / unit-test-notebook (pull_request), aby wyświetlić zielony znacznik wyboru. (Wyświetlenie ikony może potrwać kilka minut). Jeśli jest czerwony znak X zamiast zielonego znacznika wyboru, kliknij pozycję Szczegóły , aby dowiedzieć się, dlaczego. Jeśli ikona lub Szczegóły nie są już wyświetlane, kliknij przycisk Pokaż wszystkie testy.
  8. Jeśli zostanie wyświetlony zielony znacznik wyboru, scal żądanie ściągnięcia z gałęzią main .