Praktik terbaik rekayasa perangkat lunak untuk notebook

Artikel ini menyediakan panduan langsung yang menunjukkan cara menerapkan praktik terbaik rekayasa perangkat lunak ke notebook Azure Databricks Anda, termasuk kontrol versi, berbagi kode, pengujian, dan integrasi berkelanjutan opsional dan pengiriman atau penyebaran berkelanjutan (CI/CD).

Dalam panduan ini, Anda:

  • Tambahkan buku catatan ke folder git Azure Databricks untuk kontrol versi.
  • Mengekstrak bagian kode dari salah satu notebook ke dalam modul yang dapat dibagikan.
  • Menguji kode bersama.
  • Jalankan buku catatan dari pekerjaan Azure Databricks.
  • Menerapkan CI/CD ke kode bersama secara opsional.

Persyaratan

Untuk menyelesaikan panduan ini, Anda harus menyediakan sumber daya berikut:

  • Repositori jarak jauh dengan penyedia Git yang didukung Databricks. Panduan artikel ini menggunakan GitHub. Panduan ini mengasumsikan bahwa Anda memiliki repositori GitHub bernama best-notebooks tersedia. (Anda dapat memberi nama yang berbeda pada repositori Anda. Jika ya, ganti best-notebooks dengan nama repositori Anda di seluruh panduan ini.) Buat repositori GitHub jika Anda belum memilikinya.

    Catatan

    Jika Anda membuat repositori baru, pastikan untuk menginisialisasi repositori dengan setidaknya satu file, misalnya README file.

  • Ruang kerja Azure Databricks. Buat ruang kerja jika Anda belum memilikinya.

  • Kluster Azure Databricks serbaguna di ruang kerja. Untuk menjalankan notebook selama fase desain, Anda melampirkan notebook ke kluster serba guna yang sedang berjalan. Dalam langkah berikutnya, panduan langkah demi langkah ini menggunakan Azure Databricks job untuk mengotomatiskan eksekusi notebook pada kluster ini. (Anda juga dapat menjalankan pekerjaan pada kluster pekerjaan yang hanya ada untuk masa pakai pekerjaan.) Buat kluster semua tujuan jika Anda belum memilikinya.

Langkah 1: Menyiapkan folder Databricks Git

Dalam langkah ini, Anda menyambungkan repositori GitHub yang ada ke folder Git Azure Databricks di ruang kerja Azure Databricks yang ada.

Untuk mengaktifkan ruang kerja Anda agar tersambung ke repositori GitHub, Anda harus terlebih dahulu menyediakan kredensial GitHub Anda, jika Anda belum melakukannya.

Langkah 1.1: Berikan kredensial GitHub Anda

  1. Klik nama pengguna Anda di kanan atas ruang kerja, lalu klik Pengaturan di daftar drop-down.
  2. Di bilah samping di Pengaturan, di bawah Pengguna, klik Akun tertaut.
  3. Di bawah integrasi Git, untuk penyedia Git, pilih GitHub.
  4. Klik Token akses pribadi.
  5. Untuk nama pengguna atau email penyedia Git, masukkan nama pengguna GitHub Anda.
  6. Untuk Token, masukkan GitHub token akses pribadi (klasik). Token akses pribadi ini (klasik) harus memiliki izin repo dan workflow.
  7. Klik Simpan.

Langkah 1.2: Sambungkan ke repositori GitHub Anda

  1. Pada bilah sisi ruang kerja, klik Ruang Kerja.
  2. Di peramban Ruang Kerja, perluas Pengguna > Ruang Kerja.
  3. Klik kanan folder nama pengguna Anda, lalu klik Buat > folder Git.
  4. Dalam dialog Buat folder Git:
    1. Untuk URL repositori Git, masukkan URL GitHub Clone dengan HTTPS untuk repositori GitHub Anda. Artikel ini mengasumsikan bahwa URL Anda berakhir dengan best-notebooks.git, misalnya https://github.com/<your-GitHub-username>/best-notebooks.git.
    2. Untuk penyedia Git, pilih GitHub.
    3. Biarkan nama folder Git tetap diset sesuai dengan nama repositori Anda, misalnya best-notebooks.
    4. Klik Buat folder Git.

Langkah 2: Mengimpor dan menjalankan buku catatan

Dalam langkah ini, Anda mengimpor buku catatan eksternal yang sudah ada ke dalam repositori Anda. Anda dapat membuat buku catatan Anda sendiri untuk pemahaman langkah-demi-langkah ini, tetapi untuk mempercepat proses, kami menyediakan buku catatan tersebut untuk Anda di sini.

Langkah 2.1: Membuat cabang kerja di repositori

Dalam substep ini, Anda membuat cabang bernama eda di repositori Anda. Cabang ini memungkinkan Anda untuk mengerjakan file dan kode secara independen dari cabang repositori main Anda, yang merupakan praktik terbaik rekayasa perangkat lunak. (Anda dapat memberikan nama yang berbeda pada cabang Anda.)

Catatan

Dalam beberapa repositori, main cabang dapat diberi nama master sebagai gantinya. Jika demikian, ganti main dengan master di seluruh panduan ini.

Petunjuk / Saran

Jika Anda tidak terbiasa bekerja di cabang Git, lihat Cabang Git - Intisari Cabang di situs web Git.

  1. Folder Git dari Langkah 1.2 harus terbuka. Jika tidak, maka di bilah samping Ruang Kerja, perluas >, lalu perluas folder nama pengguna Anda, dan klik folder Git Anda.

  2. Di samping nama folder di bawah jejak navigasi ruang kerja, klik tombol cabang utama Git.

  3. Dalam dialog best-notebooks, klik tombol Create branch.

    Catatan

    Jika repositori Anda memiliki nama selain best-notebooks, judul dialog ini akan berbeda, di sini dan di seluruh panduan ini.

  4. Masukkan eda, dan klik Buat.

  5. Tutup dialog ini.

Langkah 2.2: Mengimpor buku catatan ke dalam repositori

Dalam substep ini, Anda mengimpor buku catatan yang sudah ada dari repositori lain ke repositori Anda. Buku catatan ini melakukan hal berikut:

  • Menyalin file CSV dari repositori owid/covid-19-data GitHub ke kluster di ruang kerja Anda. File CSV ini berisi data publik tentang rumah sakit COVID-19 dan metrik perawatan intensif dari seluruh dunia.
  • Membaca konten file CSV ke dalam DataFramepandas.
  • Memfilter data agar hanya berisi metrik dari Amerika Serikat.
  • Menampilkan plot data.
  • Menyimpan DataFrame pandas sebagai API Pandas di SparkDataFrame.
  • Melakukan pembersihan data pada API Pandas pada Spark DataFrame.
  • Menulis API Pandas di Spark DataFrame sebagai tabel Delta di ruang kerja Anda.
  • Menampilkan isi tabel Delta.

Meskipun Anda bisa membuat buku catatan Anda sendiri di repositori Anda di sini, mengimpor buku catatan yang sudah ada akan membantu mempercepat panduan ini. Untuk membuat buku catatan di cabang ini atau memindahkan buku catatan yang sudah ada ke cabang ini alih-alih mengimpor buku catatan, lihat Penggunaan dasar file Ruang Kerja.

  1. Dari folder Git buku catatan terbaik, klik Buat > Folder.
  2. Dalam dialog Folder baru, masukkan notebooks, lalu klik Buat.
  3. Dari folder buku catatan, klik ikon kebab, lalu Impor.
  4. Dalam dialog Impor :

    1. Untuk Impor dari, pilih URL .

    2. Masukkan URL ke konten mentah notebook covid_eda_raw di repositori databricks/notebook-best-practices di GitHub. Untuk mendapatkan URL ini: i. Pergi ke https://github.com/databricks/notebook-best-practices. ii. Klik folder notebooks. Iii. Klik covid_eda_raw.py file. Iv. Klik Raw. v. Salin URL lengkap dari bilah alamat browser web Anda ke dialog Impor .

      Catatan

      Dialog Impor hanya berfungsi dengan URL Git untuk repositori publik.

    3. Klik Impor.

Langkah 2.3: Jalankan buku catatan

  1. Jika buku catatan belum ditampilkan, buka folder buku catatan , lalu klik buku catatan covid_eda_raw di dalam folder.
  2. Pilih kluster untuk melampirkan buku catatan ini ke. Untuk instruksi tentang membuat kluster, lihat Membuat kluster.
  3. Klik Jalankan Semua.
  4. Tunggu sementara notebook berjalan.

Setelah buku catatan selesai berjalan, di buku catatan Anda akan melihat plot data serta lebih dari 600 baris data mentah dalam tabel Delta. Jika kluster belum berjalan saat Anda mulai menjalankan buku catatan ini, perlu waktu beberapa menit agar kluster dimulai sebelum menampilkan hasilnya.

Langkah 2.4: Cek masuk dan gabungkan buku catatan

Dalam substep ini, Anda menyimpan pekerjaan Anda sejauh ini ke repositori GitHub Anda. Anda kemudian menggabungkan buku catatan dari cabang kerja Anda ke cabang repositori main Anda.

  1. Di samping nama buku catatan, klik tombol cabang eda Git.
  2. Dalam dialog best-notebooks, pada tab Perubahan, pastikan file notebooks/covid_eda_raw.py dipilih.
  3. Untuk Terapkan pesan (diperlukan), masukkan Added raw notebook.
  4. Untuk Deskripsi (opsional), masukkan This is the first version of the notebook.
  5. Klik Commit & Unggah.
  6. Klik tautan pull request di Buat pull request di penyedia git Anda di banner.
  7. Di GitHub, buat permintaan pull, lalu gabungkan permintaan pull ke cabang main.
  8. Kembali ke ruang kerja Azure Databricks Anda, tutup dialog best-notebooks jika masih ditampilkan.

Langkah 3: Memindahkan kode ke dalam modul bersama

Dalam langkah ini, Anda memindahkan beberapa kode di buku catatan Anda ke dalam sekumpulan fungsi bersama di luar buku catatan Anda. Ini memungkinkan Anda menggunakan fungsi-fungsi ini dengan notebook serupa lainnya, yang dapat mempercepat pengkodean di masa depan dan membantu memastikan hasil notebook yang lebih dapat diprediksi dan konsisten. Berbagi kode ini juga memungkinkan Anda untuk lebih mudah menguji fungsi-fungsi ini, yang sebagai praktik terbaik rekayasa perangkat lunak dapat meningkatkan kualitas keseluruhan kode Anda saat Anda pergi.

Langkah 3.1: Membuat cabang kerja lain di repositori

  1. Di samping nama buku catatan, klik tombol cabang eda Git.
  2. Dalam dialog buku catatan terbaik , klik panah drop-down di samping cabang eda , dan pilih utama .
  3. Klik tombol Tarik . Jika diminta untuk melanjutkan penarikan, klik Konfirmasi.
  4. Klik tombol Buat Cabang .
  5. Masukkan first_modules, lalu klik Buat. (Anda dapat memberikan nama yang berbeda pada cabang Anda.)
  6. Tutup dialog ini.

Langkah 3.2: Mengimpor buku catatan ke dalam repositori

Untuk mempercepat panduan ini, dalam substep ini Anda mengimpor buku catatan lain yang sudah ada ke dalam repositori Anda. Buku catatan ini melakukan hal yang sama seperti buku catatan sebelumnya, kecuali buku catatan ini akan memanggil fungsi kode bersama yang disimpan di luar buku catatan. Sekali lagi, Anda dapat membuat buku catatan Anda sendiri di repositori Anda di sini dan melakukan berbagi kode aktual sendiri.

  1. Di jendela Ruang Kerja, klik kanan pada folder notebook, lalu klik Impor.
  2. Dalam dialog Impor :

    1. Untuk Impor dari, pilih URL .

    2. Masukkan URL ke konten mentah notebook covid_eda_modular di repositori databricks/notebook-best-practices di GitHub. Untuk mendapatkan URL ini: i. Pergi ke https://github.com/databricks/notebook-best-practices. ii. Klik folder notebooks. Iii. Klik covid_eda_modular.py file. Iv. Klik Raw. v. Salin URL lengkap dari bilah alamat browser web Anda ke dialog Impor Buku Catatan .

      Catatan

      Dialog Impor Buku Catatan hanya berfungsi dengan URL Git untuk repositori publik.

    3. Klik Impor.

Langkah 3.3: Menambahkan fungsi kode bersama yang mendukung notebook

  1. Di browser Ruang Kerja, klik kanan pada folder Git best-notebooks, lalu klik Buat > Folder.

  2. Dalam dialog Folder baru, masukkan covid_analysis, lalu klik Buat.

  3. Dari folder covid_analysis klik Buat > File.

  4. Dalam dialog Nama File Baru, masukkan transforms.py, lalu klik Buat File.

  5. Di jendela editor transforms.py, masukkan kode berikut:

    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

Petunjuk / Saran

Untuk teknik berbagi kode lainnya, lihat Berbagi kode antara notebook Databricks.

Langkah 3.4: Menambahkan dependensi kode bersama

Kode sebelumnya memiliki beberapa dependensi paket Python untuk memungkinkan kode berjalan dengan benar. Dalam substep ini, Anda mendeklarasikan dependensi paket ini. Mendeklarasikan dependensi meningkatkan reprodusibilitas dengan menggunakan versi pustaka yang ditentukan dengan tepat.

  1. Dari browser Ruang Kerja, klik kanan pada folder Git best-notebooks, lalu klik Buat > File.

    Catatan

    Anda ingin file yang mencantumkan dependensi paket masuk ke akar folder Git, bukan ke dalam buku catatan atau folder covid_analysis .

  2. Dalam dialog Nama File Baru, masukkan requirements.txt, lalu klik Buat File.

  3. Di jendela editor requirements.txt, masukkan kode berikut:

    Catatan

    Jika file requirements.txt tidak terlihat, Anda mungkin perlu me-refresh browser web Anda.

    -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

    Catatan

    File sebelumnya mencantumkan versi paket tertentu. Untuk kompatibilitas yang lebih baik, Anda dapat membandingkan versi ini dengan versi yang diinstal pada klaster serbaguna Anda. Lihat bagian "Lingkungan sistem" untuk versi Databricks Runtime kluster Anda di versi dan kompatibilitas catatan rilis Databricks Runtime.

Struktur repositori Anda sekarang akan terlihat seperti ini:

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

Langkah 3.5: Jalankan buku catatan yang direfaktor

Dalam substep ini, Anda menjalankan covid_eda_modular notebook, yang memanggil kode yang dibagikan di covid_analysis/transforms.py.

  1. Dari browser Workspace, klik notebook covid_eda_modular di folder notebooks.
  2. Pilih kluster untuk melampirkan buku catatan ini ke.
  3. Klik Jalankan Semua.
  4. Tunggu sementara notebook berjalan.

Setelah buku catatan selesai berjalan, di buku catatan Anda akan melihat hasil serupa seperti buku catatan covid_eda_raw: plot data serta lebih dari 600 baris data mentah dalam tabel Delta. Perbedaan utama dari notebook ini adalah penggunaan filter yang berbeda (sebuah iso_code dari DZA alih-alih USA). Jika kluster belum berjalan saat Anda mulai menjalankan buku catatan ini, perlu waktu beberapa menit agar kluster dimulai sebelum menampilkan hasilnya.

  1. Di samping nama buku catatan, klik tombol Git cabang first_modules.
  2. Di dalam dialog best-notebooks, pada tab Perubahan, pastikan hal berikut ini dipilih:
    • requirements.txt
    • covid_analysis/transforms.py
    • buku catatan/covid_eda_modular.py
  3. Untuk Terapkan pesan (diperlukan), masukkan Added refactored notebook.
  4. Untuk Deskripsi (opsional), masukkan This is the second version of the notebook.
  5. Klik Commit & Unggah.
  6. Klik tautan pull request di Buat pull request di penyedia git Anda di banner.
  7. Di GitHub, buat permintaan pull, lalu gabungkan permintaan pull ke cabang main.
  8. Kembali ke ruang kerja Azure Databricks Anda, tutup dialog best-notebooks jika masih ditampilkan.

Langkah 4: Uji kode bersama

Dalam langkah ini, Anda menguji kode bersama dari langkah terakhir. Namun, Anda ingin menguji kode ini tanpa menjalankan covid_eda_modular notebook itu sendiri. Ini karena jika kode bersama gagal dijalankan, buku catatan itu sendiri kemungkinan juga akan gagal dijalankan. Anda ingin menangkap kegagalan dalam kode bersama Anda terlebih dahulu sebelum notebook utama Anda akhirnya gagal nanti. Teknik pengujian ini adalah praktik terbaik rekayasa perangkat lunak.

Petunjuk / Saran

Untuk pendekatan tambahan dalam pengujian notebook, serta pengujian untuk notebook R dan Scala, lihat Pengujian unit untuk notebook.

Langkah 4.1: Membuat cabang kerja lain di repositori

  1. Di samping nama buku catatan, klik tombol Git cabang first_modules.
  2. Dalam dialog buku catatan terbaik, klik panah drop-down di samping cabang first_modules, dan pilih utama .
  3. Klik tombol Tarik . Jika diminta untuk melanjutkan penarikan, klik Konfirmasi.
  4. Klik Buat Cabang.
  5. Masukkan first_tests, lalu klik Buat. (Anda dapat memberikan nama yang berbeda pada cabang Anda.)
  6. Tutup dialog ini.

Langkah 4.2: Menambahkan pengujian

Dalam substep ini, Anda menggunakan kerangka kerja pytest untuk menguji kode bersama Anda. Dalam pengujian ini, Anda menegaskan apakah hasil pengujian tertentu tercapai. Jika ada pengujian yang menghasilkan hasil yang tidak terduga, pengujian tertentu itu gagal dalam pernyataan dan dengan demikian pengujian itu sendiri gagal.

  1. Dari Ruang Kerja browser, klik kanan folder Git Anda, lalu klik Buat folder>.

  2. Dalam dialog Folder baru, masukkan tests, lalu klik Buat.

  3. Dari folder pengujian , klik Buat > File.

  4. Dalam dialog Nama File Baru, masukkan testdata.csv, lalu klik Buat File.

  5. Di jendela editor testdata.csv, masukkan data pengujian berikut:

    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. Dari folder pengujian , klik Buat > File.

  7. Dalam dialog Nama File Baru, masukkan transforms_test.py, lalu klik Buat File.

  8. Di jendela editor transforms_test.py, masukkan kode pengujian berikut. Pengujian ini menggunakan perlengkapan standar serta DataFrame pandas dalam memori yang dimock:

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

Struktur repositori Anda sekarang akan terlihat seperti ini:

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

Langkah 4.3: Jalankan pengujian

Untuk mempercepat panduan ini, dalam langkah kecil ini Anda menggunakan buku catatan yang diimpor untuk melaksanakan pengujian yang telah disebutkan sebelumnya. Notebook ini mengunduh dan menginstal paket Python dependen pengujian ke ruang kerja Anda, menjalankan pengujian, dan melaporkan hasil pengujian. Meskipun Anda dapat menjalankan pytest dari terminal web kluster Anda, menjalankan pytest dari notebook bisa lebih nyaman.

Catatan

Menjalankan pytest akan menjalankan semua file yang namanya mengikuti pola test_*.py atau /*_test.py di direktori saat ini dan semua subdirektori.

  1. Di jendela Ruang Kerja, klik kanan pada folder notebook, lalu klik Impor.

  2. Dalam dialog Impor Buku Catatan :

    1. Untuk Impor dari, pilih URL .

    2. Masukkan URL ke konten mentah notebook run_unit_tests di repositori databricks/notebook-best-practices di GitHub. Untuk mendapatkan URL ini: i. Pergi ke https://github.com/databricks/notebook-best-practices. ii. Klik folder notebooks. Iii. Klik run_unit_tests.py file. Iv. Klik Raw. v. Salin URL lengkap dari bilah alamat browser web Anda ke dialog Impor Buku Catatan .

      Catatan

      Dialog Impor Buku Catatan hanya berfungsi dengan URL Git untuk repositori publik.

    3. Klik Impor.

  3. Pilih kluster untuk melampirkan buku catatan ini ke.

  4. Klik Jalankan Semua.

  5. Tunggu sementara notebook berjalan.

Setelah buku catatan selesai berjalan, di buku catatan Anda akan melihat informasi tentang jumlah pengujian yang lulus dan gagal, bersama dengan detail terkait lainnya. Jika kluster belum berjalan saat Anda mulai menjalankan buku catatan ini, perlu waktu beberapa menit agar kluster dimulai sebelum menampilkan hasilnya.

Struktur repositori Anda sekarang akan terlihat seperti ini:

├── covid_analysis
│  └── transforms.py
├── notebooks
│  ├── covid_eda_modular
│  ├── covid_eda_raw (optional)
│  └── run_unit_tests
├── requirements.txt
└── tests
    ├── testdata.csv
    └── transforms_test.py
  1. Di samping nama buku catatan, klik tombol cabang Git first_tests.
  2. Di dalam dialog best-notebooks, pada tab Perubahan, pastikan hal berikut ini dipilih:
    • tests/transforms_test.py
    • notebooks/run_unit_tests.py
    • tests/testdata.csv
  3. Untuk Terapkan pesan (diperlukan), masukkan Added tests.
  4. Untuk Deskripsi (opsional), masukkan These are the unit tests for the shared code..
  5. Klik Commit & Unggah.
  6. Klik tautan pull request di Buat pull request di penyedia git Anda di banner.
  7. Di GitHub, buat permintaan pull, lalu gabungkan permintaan pull ke cabang main.
  8. Kembali ke ruang kerja Azure Databricks Anda, tutup dialog best-notebooks jika masih ditampilkan.

Langkah 5: Membuat pekerjaan untuk menjalankan buku catatan

Pada langkah-langkah sebelumnya, Anda menguji kode bersama secara manual dan menjalankan buku catatan Anda secara manual. Dalam langkah ini, Anda menggunakan job Azure Databricks untuk menguji kode bersama Anda dan menjalankan notebook Anda secara otomatis, baik sesuai permintaan atau sesuai jadwal reguler.

Langkah 5.1: Membuat tugas pekerjaan untuk menjalankan buku catatan pengujian

  1. Di ruang kerja Anda, klik ikon Alur Kerja.Pekerjaan & Alur Kerja di bar samping.
  2. Klik Buat, lalu Pekerjaan.
  3. Edit nama pekerjaan menjadi covid_report.
  4. Klik petak Notebook untuk mengonfigurasi tugas pertama. Jika petak peta Notebook tidak tersedia, klik Tambahkan tipe tugas lain dan cari Notebook.
  5. Untuk Nama tugas, masukkan run_notebook_tests.
  6. Jika perlu, pilih Notebook dari menu drop-down Jenis .
  7. Untuk Sumber, pilih penyedia Git .
  8. Klik Tambahkan referensi Git.
  9. Dalam dialog Informasi Git:
    1. Untuk URL repositori Git, masukkan URL GitHub Clone dengan HTTPS untuk repositori GitHub Anda. Artikel ini mengasumsikan bahwa URL Anda berakhir dengan best-notebooks.git, misalnya https://github.com/<your-GitHub-username>/best-notebooks.git.
    2. Untuk penyedia Git, pilih GitHub.
    3. Untuk referensi Git (cabang / tag / komit), masukkan main.
    4. Di sebelah referensi Git (cabang / tag / komit), pilih cabang .
    5. Klik Konfirmasi.
  10. Untuk Jalur, masukkan notebooks/run_unit_tests. Jangan tambahkan .py ekstensi file.
  11. Untuk Kluster , pilih kluster dari langkah sebelumnya.
  12. Klik Buat tugas.

Catatan

Dalam skenario ini, Databricks tidak menyarankan agar Anda menggunakan tombol jadwal di buku catatan seperti yang dijelaskan dalam Membuat dan mengelola pekerjaan buku catatan terjadwal untuk menjadwalkan pekerjaan untuk menjalankan buku catatan ini secara berkala. Ini karena tombol jadwal membuat tugas dengan menggunakan salinan terbaru notebook yang sedang berfungsi di repositori ruang kerja. Sebagai gantinya, Databricks merekomendasikan agar Anda mengikuti instruksi sebelumnya untuk membuat pekerjaan yang menggunakan versi notebook terbaru yang diterapkan di repositori.

Langkah 5.2: Membuat tugas pekerjaan untuk menjalankan buku catatan utama

  1. Klik ikon + Tambahkan tugas.
  2. Menu pop-up muncul. Pilih Buku Catatan.
  3. Untuk Nama tugas, masukkan run_main_notebook.
  4. Untuk Tipe, pilih Notebook.
  5. Untuk Jalur, masukkan notebooks/covid_eda_modular. Jangan tambahkan .py ekstensi file.
  6. Untuk Kluster , pilih kluster dari langkah sebelumnya.
  7. Pastikan Nilai yang tergantung adalah run_notebook-tests.
  8. Klik Buat tugas.

Langkah 5.3 Jalankan pekerjaan

  1. Klik Jalankan sekarang.

  2. Pada jendela pop-up, klik Lihat jalankan.

    Catatan

    Jika pop-up menghilang terlalu cepat, lakukan hal berikut:

    1. Pada bilah samping di lingkungan Data Science & Engineering atau Databricks Mosaic AI, klik Jobs & Pipelines.
    2. Pada tab Job yang berjalan, klik nilai Waktu mulai untuk tugas terbaru dengan covid_report di kolom Tugas.

  3. Untuk melihat hasil pekerjaan, klik pada ubin run_notebook_tests, run_main_notebook, atau keduanya. Hasil pada setiap petak peta sama seperti jika Anda menjalankan buku catatan sendiri, satu per satu.

Catatan

Pekerjaan ini dijalankan sesuai permintaan. Untuk menyiapkan pekerjaan ini agar berjalan secara teratur, lihat Mengotomatiskan pekerjaan dengan jadwal dan pemicu.

(Opsional) Langkah 6: Siapkan repositori untuk menguji kode dan menjalankan buku catatan secara otomatis setiap kali kode berubah

Pada langkah sebelumnya, Anda menggunakan tugas untuk menguji kode bersama Anda secara otomatis dan menjalankan buku catatan Anda pada waktu tertentu atau secara berulang. Namun, Anda mungkin lebih suka memicu pengujian secara otomatis ketika perubahan digabungkan ke dalam repositori GitHub Anda, menggunakan alat CI/CD seperti GitHub Actions.

Langkah 6.1: Menyiapkan akses GitHub ke ruang kerja Anda

Dalam substep ini, Anda menyiapkan alur kerja GitHub Actions yang menjalankan pekerjaan di ruang kerja setiap kali perubahan digabungkan ke dalam repositori Anda. Anda melakukan ini dengan memberikan GitHub token Azure Databricks unik untuk akses.

Untuk alasan keamanan, Databricks mencegah Anda memberikan token akses pribadi pengguna ruang kerja Azure Databricks anda ke GitHub. Sebaliknya, Databricks merekomendasikan agar Anda memberikan GitHub token Microsoft Entra ID yang terkait dengan perwakilan layanan Microsoft Entra ID. Untuk petunjuknya, lihat bagian Azure dari halaman Jalankan Tindakan GitHub Notebook Databricks di Marketplace GitHub Actions.

Penting

Notebook dijalankan dengan semua izin ruang kerja identitas yang terkait dengan token, sehingga Databricks merekomendasikan penggunaan perwakilan layanan. Jika Anda benar-benar ingin memberikan token akses pribadi pengguna ruang kerja Azure Databricks Anda ke GitHub hanya untuk tujuan eksplorasi pribadi, dan Anda memahami bahwa untuk alasan keamanan Databricks mencegah praktik ini, lihat instruksi untuk buat token akses pribadi pengguna ruang kerja Anda.

Langkah 6.2: Menambahkan alur kerja GitHub Actions

Dalam substep ini, Anda menambahkan alur kerja GitHub Actions untuk menjalankan notebook run_unit_tests setiap kali ada permintaan pull ke repositori.

Substep ini menyimpan alur kerja GitHub Actions dalam file yang disimpan dalam beberapa tingkat folder di repositori GitHub Anda. GitHub Actions memerlukan hierarki folder berlapis tertentu agar ada di repositori Anda agar berfungsi dengan baik. Untuk menyelesaikan langkah ini, Anda harus menggunakan situs web untuk repositori GitHub Anda, karena antarmuka pengguna folder Git Azure Databricks tidak mendukung pembuatan hierarki folder berlapis.

  1. Di situs web untuk repositori GitHub Anda, klik tab Code.

  2. Klik panah di samping utama untuk memperluas daftar drop-down Beralih cabang atau tag.

  3. Dalam kotak Temukan atau buat cabang , masukkan adding_github_actions.

  4. Klik Buat cabang: adding_github_actions dari 'main'.

  5. Klik Tambahkan file > Buat file baru.

  6. Untuk Beri nama file Anda, masukkan .github/workflows/databricks_pull_request_tests.yml.

  7. Di jendela editor, masukkan kode berikut. Kode ini menggunakan hook pull_request dari Run Databricks Notebook GitHub Action untuk menjalankan notebook run_unit_tests.

    Dalam kode berikut, ganti:

    • <your-workspace-instance-URL> dengan nama Azure Databricks instance Anda.
    • <your-access-token> dengan token yang Anda buat sebelumnya.
    • <your-cluster-id> dengan ID komputasi klasik target Anda.
    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. Klik Terapkan perubahan.

  9. Dalam dialog Commit changes, masukkan Create databricks_pull_request_tests.yml ke dalam Commit message

  10. Pilih Terapkan langsung ke cabang adding_github_actions dan klik Terapkan perubahan.

  11. Pada tab Kode, klik Bandingkan & buat pull request, lalu buat pull request.

  12. Pada halaman pull request, tunggu hingga ikon di samping Jalankan pengujian Databricks pra-gabung / unit-test-notebook (pull_request) menampilkan tanda centang hijau. (Mungkin perlu beberapa saat agar ikon muncul.) Jika ada X merah alih-alih tanda centang hijau, klik Detail untuk mengetahui alasannya. Jika ikon atau Detail tidak lagi ditampilkan, klik Perlihatkan semua pemeriksaan.

  13. Jika tanda centang hijau muncul, gabungkan permintaan tarik ke cabang main.

(Opsional) Langkah 7: Perbarui kode bersama di GitHub untuk memicu pengujian

Dalam langkah ini, Anda membuat perubahan pada kode bersama lalu mendorong perubahan ke repositori GitHub Anda, yang segera memicu pengujian secara otomatis, berdasarkan Tindakan GitHub dari langkah sebelumnya.

Langkah 7.1: Membuat cabang kerja lain di repositori

  1. Dari browser Workspace, buka folder Git best-notebooks.
  2. Di sebelah nama folder, klik tombol cabang Git first_tests.
  3. Dalam dialog buku catatan terbaik , klik panah turun di sebelah cabang first_tests, dan pilihutama.
  4. Klik tombol Tarik . Jika diminta untuk melanjutkan penarikan, klik Konfirmasi.
  5. Klik tombol + (Buat cabang) .
  6. Masukkan trigger_tests, lalu klik Buat. (Anda dapat memberikan nama yang berbeda pada cabang Anda.)
  7. Tutup dialog ini.

Langkah 7.2: Mengubah kode bersama

  1. Dari peramban Workspace, di folder Git best-notebooks, klik file covid_analysis/transforms.py .

  2. Ubah baris ketiga file ini:

    # Filter by country code.

    Untuk ini:

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

Langkah 7.3: Periksa perubahan untuk memicu pengujian

  1. Di samping nama file, klik tombol cabang Git trigger_tests.
  2. Dalam dialog best-notebooks, pada tab Perubahan, pastikan covid_analysis/transforms.py dipilih.
  3. Untuk Terapkan pesan (diperlukan), masukkan Updated comment.
  4. Untuk Deskripsi (opsional), masukkan This updates the comment for filter_country.
  5. Klik Commit & Unggah.
  6. Klik tautan permintaan pull di Buat permintaan pull pada penyedia git Anda di banner, lalu buat permintaan pull di GitHub.
  7. Pada halaman pull request, tunggu hingga ikon di samping Jalankan pengujian Databricks pra-gabung / unit-test-notebook (pull_request) menampilkan tanda centang hijau. (Mungkin perlu beberapa saat agar ikon muncul.) Jika ada X merah alih-alih tanda centang hijau, klik Detail untuk mengetahui alasannya. Jika ikon atau Detail tidak lagi ditampilkan, klik Perlihatkan semua pemeriksaan.
  8. Jika tanda centang hijau muncul, gabungkan permintaan tarik ke cabang main.
  • Last updated on