Najlepsze praktyki inżynierii oprogramowania dla notatników

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 notatniki z pracy na platformie Azure Databricks.
• Opcjonalnie zastosuj CI/CD na wspólnym kodzie.

Wymagania

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

• Zdalne repozytorium z dostawcą Git obsługiwanym przez Databricks. W tym artykule przedstawiono sposób użycia usługi GitHub. W tym przewodniku założono, że masz dostępne repozytorium GitHub o nazwie best-notebooks. (Możesz nadać repozytorium inną nazwę. Jeśli to zrobisz, zastąp nazwę „best-notebooks” nazwą swojego repozytorium w tym przewodniku). Utwórz repozytorium GitHub jeśli jeszcze go nie masz.

  Uwaga

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

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

• Klaster ogólnego przeznaczenia usługi Azure Databricks w obszarze roboczym. Aby uruchamiać notesy w fazie projektowania, dołącz je do uruchomionego klastra o ogólnym przeznaczeniu. W dalszej części tego przewodnika użyto zadania usługi Azure Databricks w celu zautomatyzowania uruchamiania notebooków w tym klastrze. (Można również uruchamiać zadania w klastrach utworzonych dla zadań , które istnieją wyłącznie przez czas trwania zadań). Utwórz klaster uniwersalny, 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ę Token dostępu osobistego.
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 do repo i workflow.
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ń Obszar roboczy > Użytkownicy.
3. Kliknij prawym przyciskiem myszy na folder z nazwą użytkownika, a następnie kliknij >.
4. W oknie dialogowym Tworzenie folderu Git:
   1. W polu Adres URL repozytorium Git wprowadź adres URL Klonuj za pomocą protokołu HTTPS dla swojego repozytorium GitHub. 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 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: Utwórz gałąź roboczą 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ę).

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

2. Obok nazwy folderu w nawigacji przestrzeni roboczej 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, jak i w całym tym przewodniku.

4. Wprowadź eda, a następnie kliknij Utwórz.

5. Zamknij to okno dialogowe.

Krok 2.2. Importowanie notesu do repozytorium

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

• Kopiuje plik CSV z repozytorium GitHub owid/covid-19-data do klastra w obszarze roboczym. Ten plik CSV zawiera publiczne dane dotyczące hospitalizacji COVID-19 i metryk intensywnej terapii z całego świata.
• Odczytuje zawartość pliku CSV do DataFramebiblioteki pandas.
• Filtruje dane tak, aby zawierały metryki tylko z Stany Zjednoczone.
• Wyświetla wykres danych.
• Zapisuje ramkę danych w formacie Pandas API na platformie Spark.
• Przeprowadza czyszczenie danych za pomocą interfejsu API Pandas na ramce danych Spark.
• Zapisuje interfejs API Pandas na DataFrame platformy Spark jako tabelę Delta w Twoim obszarze roboczym.
• Wyświetla zawartość tabeli delty.

Chociaż możesz utworzyć własny notes w repozytorium tutaj, importowanie istniejącego notesu zamiast tego pomaga przyspieszyć ten przebieg. 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. Z folderu best-notebooks w Git kliknij 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 do nieprzetworzonej zawartości notesu covid_eda_raw w repozytorium databricks/notebook-best-practices na GitHubie. Aby uzyskać ten adres URL: i. Przejdź do https://github.com/databricks/notebook-best-practices. Ii. Kliknij folder notebooks. Iii. Kliknij covid_eda_raw.py plik. Iv. Kliknij Surowe. kontra Skopiuj pełny adres URL z paska adresu przeglądarki internetowej do okna dialogowego Importowanie .

      Uwaga

      Okno dialogowe Import 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 notatnik nie jest jeszcze wyświetlany, otwórz folder notatników, a następnie kliknij notatnik 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 opcję 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: Sprawdź i scal notatnik

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

1. Obok nazwy notesu kliknij przycisk gałęzi Git eda.
2. W oknie dialogowym best-notebooks na karcie Zmiany upewnij się, że wybrano plik notebooks/covid_eda_raw.py.
3. W Komunikacie zatwierdzenia (wymaganym) wprowadź Added raw notebook.
4. W polu Opis (opcjonalnie)wprowadź This is the first version of the notebook.
5. Kliknij Zatwierdź i wypchnij.
6. Kliknij link do pull requestu w Utwórz pull request u dostawcy usług git na banerze.
7. W usłudze GitHub utwórz żądanie ściągnięcia, a następnie scal żądanie ściągnięcia do gałęzi main.
8. Po powrocie do obszaru roboczego usługi Azure Databricks zamknij okno dialogowe ‘najlepsze notesy’, jeśli jest nadal 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 Git eda.
2. W oknie dialogowym najlepszych notatników kliknij strzałkę listy rozwijanej obok gałęzi i wybierz główną.
3. Kliknij przycisk Pull. 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, już istniejący notatnik 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. W przypadku Importuj z, wybierz adres URL.

   2. Wprowadź adres URL do nieprzetworzonej zawartości notesu covid_eda_modular w repozytorium databricks/notebook-best-practices na GitHubie. Aby uzyskać ten adres URL: i. Przejdź do https://github.com/databricks/notebook-best-practices. Ii. Kliknij folder notebooks. Iii. Kliknij covid_eda_modular.py plik. Iv. Kliknij Surowe. kontra Skopiuj pełny adres URL z paska adresu przeglądarki internetowej do okna dialogowego Importowanie notesów .

      Uwaga

      Okno dialogowe Importowania Notesów obsługuje tylko adresy URL Git dla repozytoriów publicznych.

   3. Kliknij przycisk Importuj.

Krok 3.3: Dodawanie funkcji wspomagających udostępnionego kodu notesu

1. W przeglądarce Obszar roboczy kliknij prawym przyciskiem myszy folder Git best-notebooks, a następnie kliknij 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
   

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 Utwórz > plik.

   Uwaga

   Chcesz, aby plik zawierający listę zależności pakietów trafił do katalogu głównego folderu Git, zamiast do notebooks lub folderu 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 porównać te wersje z tymi, które są zainstalowane w uniwersalnym klastrze. Zobacz sekcję "Środowisko systemowe" dla wersji Databricks Runtime klastra w artykule "Informacje o wersji Databricks Runtime - wersje i zgodność".

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: Uruchom refaktoryzowany notatnik

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 notatnik covid_eda_modular w folderze notatniki.
2. Wybierz klaster, aby połączyć ten notes z.
3. Kliknij opcję Uruchom wszystko.
4. Zaczekaj na uruchomienie notesu.

Po zakończeniu działania notatnika w notatniku powinny zostać wyświetlone podobne wyniki jak w notatniku covid_eda_raw: wykres danych, a także ponad 600 wierszy surowych danych w tabeli Delta. Główną różnicą w tym notatniku jest użycie innego filtra (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.

Krok 3.6. Zaewidencjonuj notes i powiązany kod

1. Obok nazwy notesu kliknij przycisk gałęzi Git first_modules.
2. W oknie dialogowym Najlepsze notesy na karcie Zmiany upewnij się, że wybrano następujące opcje:
   • requirements.txt
   • covid_analysis/transforms.py
   • notatniki/covid_eda_modular.py
3. W Komunikacie zatwierdzenia (wymaganym) wprowadź Added refactored notebook.
4. W polu Opis (opcjonalnie)wprowadź This is the second version of the notebook.
5. Kliknij Zatwierdź i wypchnij.
6. Kliknij link do pull requestu w Utwórz pull request u dostawcy usług git na banerze.
7. W usłudze GitHub utwórz żądanie ściągnięcia, a następnie scal żądanie ściągnięcia do gałęzi main.
8. Po powrocie do obszaru roboczego usługi Azure Databricks zamknij okno dialogowe ‘najlepsze notesy’, jeśli jest nadal 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 notatnika covid_eda_modular. Jest to spowodowane tym, że jeśli nie można uruchomić kodu udostępnionego, sam notes prawdopodobnie również nie uda się uruchomić. 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.

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

1. Obok nazwy notesu kliknij przycisk gałęzi Git first_modules.
2. W oknie dialogowym best-notebooks kliknij strzałkę listy rozwijanej obok gałęzi first_modules i wybierz main.
3. Kliknij przycisk Pull. 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 mockowaną w pamięci ramkę 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ć to przejście, w tym podkroku użyjesz zaimportowanego notatnika do wykonania poprzednich testów. Ten notatnik pobiera i instaluje zależne pakiety Python potrzebne do testów w obszarze roboczym, uruchamia testy oraz raportuje ich wyniki. Chociaż można uruchomić polecenie pytest z terminalu internetowego klastra, uruchomienie polecenia pytest z notatnika może być wygodniejsze.

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. W przypadku Importuj z, wybierz adres URL.

   2. Wprowadź adres URL do nieprzetworzonej zawartości notesu run_unit_tests w repozytorium databricks/notebook-best-practices na GitHubie. Aby uzyskać ten adres URL: i. Przejdź do https://github.com/databricks/notebook-best-practices. Ii. Kliknij folder notebooks. Iii. Kliknij run_unit_tests.py plik. Iv. Kliknij Surowe. kontra Skopiuj pełny adres URL z paska adresu przeglądarki internetowej do okna dialogowego Importowanie notesów .

      Uwaga

      Okno dialogowe Importowania Notesów obsługuje tylko adresy URL Git dla repozytoriów publicznych.

   3. Kliknij przycisk Importuj.

3. Wybierz klaster, aby połączyć ten notes z.

4. Kliknij opcję 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 sukcesem 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

Krok 4.4. Sprawdź w notatniku i powiązanych testach

1. Obok nazwy notesu kliknij przycisk gałęzi Git first_tests.
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/dane_testowe.csv
3. W Komunikacie zatwierdzenia (wymaganym) wprowadź Added tests.
4. W polu Opis (opcjonalnie)wprowadź wartość These are the unit tests for the shared code..
5. Kliknij Zatwierdź i wypchnij.
6. Kliknij link do pull requestu w Utwórz pull request u dostawcy usług git na banerze.
7. W usłudze GitHub utwórz żądanie ściągnięcia, a następnie scal żądanie ściągnięcia do gałęzi main.
8. Po powrocie do obszaru roboczego usługi Azure Databricks zamknij okno dialogowe ‘najlepsze notesy’, jeśli jest nadal wyświetlane.

Krok 5. Tworzenie zadania do uruchamiania notesów

W poprzednich krokach ręcznie testowałeś swój udostępniony kod i ręcznie uruchamiałeś 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. Utwórz zadanie pracy w celu uruchomienia notesu testowego

1. W obszarze roboczym kliknij Zadania i rury na pasku bocznym.
2. Kliknij pozycję Utwórz, a następnie pozycję Zadanie.
3. Edytuj nazwę zadania, aby mieć wartość covid_report.
4. Kliknij kafelek Notebook, aby skonfigurować pierwsze zadanie. Jeśli kafelek Notes jest niedostępny, kliknij pozycję Dodaj inny typ zadania i wyszukaj pozycję Notes.
5. Wprowadź w polu run_notebook_tests.
6. W razie potrzeby wybierz pozycję Notes z menu rozwijanego Typ .
7. Dla źródła, wybierz dostawcę Git .
8. Kliknij Dodaj odwołanie do gita.
9. W oknie dialogowym Informacje o Git:
   1. W polu Adres URL repozytorium Git wprowadź adres URL Klonuj za pomocą protokołu HTTPS dla swojego repozytorium GitHub. 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. W polu Odniesienie do Git (gałąź/tag/zatwierdzenie), wprowadź main.
   4. Obok odniesienia Git (gałąź/tag/zatwierdzenie)wybierz gałąź.
   5. Kliknij przycisk Potwierdź.
10. W polu Ścieżka wprowadź wartość notebooks/run_unit_tests. Nie należy dodawać .py rozszerzenia pliku.
11. W przypadku Clusterwybierz klaster z poprzedniego kroku.
12. Kliknij pozycję Utwórz zadanie.

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

1. Kliknij ikonę + Dodaj zadanie .
2. Pojawi się menu podręczne. Wybierz pozycję Notebook.
3. Wprowadź w polu 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ść w polu zależy odrun_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. W pasku bocznym środowiska Data Science & Engineering lub Databricks Mosaic AI kliknij opcję Zadania i potoki.
   2. Na karcie Uruchomienia zadań kliknij wartość Czas 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 gdybyś uruchamiał notatniki jeden po drugim samodzielnie.

(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. Możesz woleć automatycznie wyzwalać testy, gdy zmiany zostaną scalone do repozytorium w GitHubie, używając narzędzia CI/CD, 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 Databricks zaleca nadanie GitHub tokenu Microsoft Entra ID skojarzonego z głównym identyfikatorem usługi Microsoft Entra ID. Aby uzyskać instrukcje, zobacz sekcję Azure na stronie Run Databricks Notebook GitHub Action w witrynie GitHub Actions Marketplace.

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 notatnik za każdym razem, gdy istnieje pull request do repozytorium.

Ten podstep przechowuje przepływ pracy funkcji GitHub Actions w pliku przechowywanym na wielu poziomach folderów w repozytorium GitHub. GitHub Actions wymaga istnienia określonej hierarchii zagnieżdżonych folderów w repozytorium, aby działać prawidłowo. Aby wykonać ten krok, musisz użyć strony internetowej repozytorium GitHub, ponieważ interfejs użytkownika folderów Git w Azure Databricks nie obsługuje tworzenia hierarchii zagnieżdżonych folderów.

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 Utwórz gałąź: adding_github_actions z '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 hooka pull_request z Run Databricks Notebook GitHub Action do uruchamiania notesu run_unit_tests.

   W poniższym kodzie zastąp:

   • <your-workspace-instance-URL> z nazwą instancji Azure Databricks.
   • <your-access-token> za pomocą wygenerowanego wcześniej tokenu.
   • <your-cluster-id> z docelowym klasycznym identyfikatorem obliczeniowym.

   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 do komunikatu Zatwierdzanie

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

11. Na karcie Kod kliknij Porównaj i prośba o scalenie, a następnie utwórz prośbę o scalenie.

12. Na stronie zgłoszenia pull request, poczekaj, aż ikona obok Uruchom testy Databricks przed scaleniem / unit-test-notebook (pull_request) 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 gałęzi Git first_tests.
3. W oknie dialogowym best-notebooks kliknij strzałkę obok gałęzi first_tests i wybierz main.
4. Kliknij przycisk Pull. 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. Zaloguj zmianę, aby uruchomić testy

1. Obok nazwy pliku kliknij przycisk gałęzi Git trigger_tests.
2. W oknie dialogowym Najlepsze notesy na karcie Zmiany upewnij się, że wybrano covid_analysis/transforms.py.
3. W Komunikacie zatwierdzenia (wymaganym) wprowadź Updated comment.
4. W polu Opis (opcjonalnie)wprowadź This updates the comment for filter_country.
5. Kliknij Zatwierdź i wypchnij.
6. Kliknij link do pull requesta w Utwórz pull request u swojego dostawcy git, a następnie utwórz pull request w usłudze GitHub.
7. Na stronie zgłoszenia pull request, poczekaj, aż ikona obok Uruchom testy Databricks przed scaleniem / unit-test-notebook (pull_request) 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 .