NotebookUtils eksekusi buku catatan dan orkestrasi

Gunakan utilitas notebook untuk menjalankan buku catatan, menjalankan beberapa buku catatan secara paralel, atau keluar dari buku catatan dengan nilai. Jalankan perintah berikut untuk mendapatkan gambaran umum tentang metode yang tersedia:

notebookutils.notebook.help()

Tabel berikut ini mencantumkan metode pelaksanaan dan orkestrasi notebook yang tersedia:

Metode	Signature	Deskripsi
`run`	`run(path: str, timeout_seconds: int = 90, arguments: dict = None, workspace: str = ""): str`	Menjalankan notebook dan mengembalikan nilai keluarnya.
`runMultiple`	`runMultiple(dag: Any, config: dict = None): dict[str, dict[str, Any]]`	Menjalankan beberapa buku catatan secara bersamaan dengan dukungan untuk hubungan dependensi.
`validateDAG`	`validateDAG(dag: Any): bool`	Memvalidasi apakah definisi DAG disusun dengan benar.
`exit`	`exit(value: str): None`	Keluar dari notebook saat ini dengan suatu nilai.

Untuk operasi CRUD buku catatan (buat, dapatkan, perbarui, hapus, daftar), lihat Mengelola artefak buku catatan.

Nota

Parameter config di runMultiple() hanya tersedia di Python. Scala dan R tidak mendukung parameter ini.

Nota

Utilitas notebook tidak berlaku untuk definisi kerja Apache Spark (SJD).

Rujuk buku catatan

Metode run() mengacu pada notebook dan mengembalikan nilai keluarnya. Anda bisa menjalankan panggilan fungsi nesting di notebook secara interaktif atau dalam alur. Notebook yang dirujuk berjalan pada kumpulan Spark dari notebook yang memanggil fungsi ini.

notebookutils.notebook.run("notebook name", <timeout_seconds>, <arguments>, <workspace>)

Contohnya:

notebookutils.notebook.run("Sample1", 90, {"input": 20 })

notebookutils.notebook.run("Sample1", 90, Map("input" -> 20), "")

notebookutils.notebook.run("Sample1", 90, list(input = 20), "")

Mengembalikan nilai

Metode mengembalikan run() string yang tepat yang diteruskan ke notebookutils.notebook.exit(value) dalam buku catatan anak. Jika exit() tidak dipanggil di buku catatan anak, string kosong ("") dikembalikan.

Notebook Fabric juga mendukung referensi notebook di seluruh ruang kerja dengan menentukan ID ruang kerja.

notebookutils.notebook.run("Sample1", 90, {"input": 20 }, "fe0a6e2a-a909-4aa3-a698-0a651de790aa")

notebookutils.notebook.run("Sample1", 90, Map("input" -> 20), "fe0a6e2a-a909-4aa3-a698-0a651de790aa")

notebookutils.notebook.run("Sample1", 90, list(input = 20), "fe0a6e2a-a909-4aa3-a698-0a651de790aa")

Buka tautan rekam jepret dalam output sel untuk memeriksa eksekusi referensi. Cuplikan menangkap hasil eksekusi dan membantu Anda men-debug buku catatan yang dirujuk.

Menyiapkan buku catatan anak untuk menerima parameter

Saat Anda membuat buku catatan anak yang dipanggil melalui run() atau runMultiple(), siapkan sel parameter sehingga buku catatan bisa menerima argumen dari induk:

Buat sel kode dengan nilai parameter default.
Tandai sel sebagai sel parameter dengan memilih Tandai sel sebagai parameter di UI buku catatan.
Selama eksekusi, nilai sel parameter diganti dengan argumen yang diteruskan dari induk.

# This cell should be marked as "parameters" cell
# Default values are overridden when the notebook is called
date = "2024-01-01"
region = "US"

Tip

Nilai keluaran selalu berupa string. Jika Anda memerlukan nilai numerik di buku catatan induk, konversikan hasil setelah pengambilan (misalnya, int(result)).

Pertimbangan

Notebook referensi lintas ruang kerja didukung oleh runtime versi 1.2 ke atas.
Jika Anda menggunakan file di bawah Sumber Daya Buku Catatan, gunakan notebookutils.nbResPath di buku catatan yang dirujuk untuk memastikannya menunjuk ke folder yang sama dengan eksekusi interaktif.
Pengoperasian referensi memungkinkan buku catatan anak berjalan hanya jika mereka menggunakan "lakehouse" yang sama dengan buku catatan utama, mewarisi "lakehouse" tersebut, atau tidak menentukannya. Eksekusi diblokir jika notebook anak menentukan lakehouse yang berbeda dari notebook induk. Untuk melewati pemeriksaan ini, atur useRootDefaultLakehouse: True dalam argumen.
Jangan memanggil notebookutils.notebook.exit(value) di dalam blok try-catch. Panggilan keluar tidak akan berlaku saat dibungkus dalam penanganan pengecualian.

Referensi menjalankan beberapa buku catatan secara paralel

Gunakan notebookutils.notebook.runMultiple() untuk menjalankan beberapa buku catatan secara paralel atau dalam struktur topologi yang telah ditentukan sebelumnya. API menggunakan implementasi multithread dalam sesi Spark, yang berarti notebook yang direferensikan menjalankan berbagi sumber daya komputasi.

Dengan notebookutils.notebook.runMultiple(), Anda dapat:

Jalankan beberapa notebook secara bersamaan, tanpa menunggu masing-masing selesai.
Tentukan dependensi dan urutan eksekusi untuk notebook Anda, menggunakan format JSON sederhana.
Optimalkan penggunaan sumber daya komputasi Spark dan kurangi biaya proyek Fabric Anda.
Tampilkan Cuplikan dari setiap catatan eksekusi notebook dalam output, dan debug dan pantau tugas notebook Anda dengan mudah.
Dapatkan nilai keluar dari setiap aktivitas eksekutif dan gunakan dalam tugas hilir.

Jalankan notebookutils.notebook.help("runMultiple") untuk melihat lebih banyak contoh dan detail penggunaan.

Jalankan daftar notebook sederhana

Contoh berikut menjalankan daftar buku catatan secara paralel:

notebookutils.notebook.runMultiple(["NotebookSimple", "NotebookSimple2"])

notebookutils.notebook.runMultiple(Seq("NotebookSimple", "NotebookSimple2"))

notebookutils.notebook.runMultiple(list("NotebookSimple", "NotebookSimple2"))

Hasil eksekusi dari buku catatan akar adalah sebagai berikut:

Mengembalikan nilai

Metode runMultiple() mengembalikan sebuah kamus di mana setiap kunci adalah nama aktivitas dan setiap nilai adalah kamus dengan kunci berikut:

exitVal: String yang dikembalikan oleh panggilan exit() dari buku catatan anak, atau string kosong jika exit() belum dipanggil.
exception: Objek kesalahan jika aktivitas gagal, atau None jika berhasil.

Menjalankan buku catatan dengan struktur DAG

Contoh berikut menjalankan notebook dalam struktur DAG dengan menggunakan notebookutils.notebook.runMultiple().

# run multiple notebooks with parameters
DAG = {
    "activities": [
        {
            "name": "Process_1", # activity name, must be unique
            "path": "NotebookSimple", # notebook item name
            "timeoutPerCellInSeconds": 90, # max timeout for each cell, default to 90 seconds
            "args": {"p1": "changed value", "p2": 100}, # notebook parameters
            "workspace":"WorkspaceName" # both name and id are supported
        },
        {
            "name": "Process_2",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 2", "p2": 200},
            "workspace":"id" # both name and id are supported
        },
        {
            "name": "Process_1.1",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 3", "p2": 300},
            "retry": 1,
            "retryIntervalInSeconds": 10,
            "dependencies": ["Process_1"] # list of activity names that this activity depends on
        }
    ],
    "timeoutInSeconds": 43200, # max timeout for the entire DAG, default to 12 hours
    "concurrency": 12 # max number of notebooks to run concurrently, default to 3x CPU cores, 0 means unlimited
}
notebookutils.notebook.runMultiple(DAG, {"displayDAGViaGraphviz": False})

val dag =
    """
        |{
        |  "activities": [
        |    {
        |      "name": "Process_1",
        |      "path": "NotebookSimple",
        |      "timeoutPerCellInSeconds": 90,
        |      "args": {"p1": "changed value", "p2": 100},
        |      "workspace": "WorkspaceName"
        |    },
        |    {
        |      "name": "Process_2",
        |      "path": "NotebookSimple2",
        |      "timeoutPerCellInSeconds": 120,
        |      "args": {"p1": "changed value 2", "p2": 200},
        |      "workspace": "id"
        |    },
        |    {
        |      "name": "Process_1.1",
        |      "path": "NotebookSimple2",
        |      "timeoutPerCellInSeconds": 120,
        |      "args": {"p1": "changed value 3", "p2": 300},
        |      "retry": 1,
        |      "retryIntervalInSeconds": 10,
        |      "dependencies": ["Process_1"]
        |    }
        |  ],
        |  "timeoutInSeconds": 43200,
        |  "concurrency": 12
        |}
        |""".stripMargin

notebookutils.notebook.runMultiple(dag)

DAG <- '{
    "activities": [
        {
            "name": "Process_1",
            "path": "NotebookSimple",
            "timeoutPerCellInSeconds": 90,
            "args": {"p1": "changed value", "p2": 100},
            "workspace": "WorkspaceName"
        },
        {
            "name": "Process_2",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 2", "p2": 200},
            "workspace": "id"
        },
        {
            "name": "Process_1.1",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 3", "p2": 300},
            "retry": 1,
            "retryIntervalInSeconds": 10,
            "dependencies": ["Process_1"]
        }
    ],
    "timeoutInSeconds": 43200,
    "concurrency": 12
}'

notebookutils.notebook.runMultiple(DAG)

Hasil eksekusi dari buku catatan akar adalah sebagai berikut:

Referensi parameter DAG

Tabel berikut ini menjelaskan setiap bidang yang bisa Anda gunakan dalam definisi DAG:

Ladang	Tingkat	Required	Deskripsi
`activities`	Akar	Yes	Daftar objek aktivitas yang menentukan buku catatan yang akan dijalankan.
`timeoutInSeconds`	Akar	No	Batas waktu maksimum untuk seluruh DAG. Defaultnya adalah 43200 (12 jam).
`concurrency`	Akar	No	Jumlah maksimum buku catatan yang akan dijalankan secara bersamaan. Defaultnya adalah 3 kali jumlah inti CPU yang tersedia. Atur nilai ini secara eksplisit jika Anda memerlukan kontrol yang lebih ketat, atau gunakan `0` untuk konkurensi tak terbatas.
`name`	Aktivitas	Yes	Nama unik untuk aktivitas tersebut. Digunakan untuk mengidentifikasi hasil dan menentukan dependensi.
`path`	Aktivitas	Yes	Nama atau jalur item buku catatan yang akan dijalankan.
`timeoutPerCellInSeconds`	Aktivitas	No	Batas waktu maksimum untuk setiap sel di buku catatan anak. Defaultnya adalah 90 detik.
`args`	Aktivitas	No	Kamus parameter untuk diteruskan ke buku catatan anak.
`workspace`	Aktivitas	No	Nama ruang kerja atau ID tempat buku catatan berada. Secara default, buku catatan anak berjalan di ruang kerja yang sama dengan pemanggil.
`retry`	Aktivitas	No	Jumlah upaya coba lagi jika aktivitas gagal. Nilai bawaan adalah 0.
`retryIntervalInSeconds`	Aktivitas	No	Waktu tunggu dalam detik setiap kali mencoba lagi. Nilai bawaan adalah 0.
`dependencies`	Aktivitas	No	Daftar nama aktivitas yang harus diselesaikan sebelum aktivitas ini dimulai.

Nilai keluaran referensi antar aktivitas

Anda dapat merujuk pada nilai keluaran dari aktivitas dependensi di bidang args dengan menggunakan ekspresi @activity(). Pola ini memungkinkan Anda meneruskan data antar notebook dalam DAG.

DAG = {
    "activities": [
        {
            "name": "Extract",
            "path": "ExtractData",
            "timeoutPerCellInSeconds": 120,
            "args": {"source": "prod_db"}
        },
        {
            "name": "Transform",
            "path": "TransformData",
            "timeoutPerCellInSeconds": 180,
            "args": {
                "data_path": "@activity('Extract').exitValue()"
            },
            "dependencies": ["Extract"]
        }
    ]
}

results = notebookutils.notebook.runMultiple(DAG)

Tip

Gunakan ekspresi @activity('activity_name').exitValue() di bidang args untuk meneruskan hasil dari satu aktivitas ke aktivitas lain dalam DAG.

Membangun DAG dinamis

Anda dapat menghasilkan struktur DAG secara terprogram untuk skenario seperti pemrosesan fan-out di beberapa partisi:

def create_fan_out_dag(partitions):
    activities = []

    for partition in partitions:
        activities.append({
            "name": f"Process_{partition}",
            "path": "ProcessPartition",
            "timeoutPerCellInSeconds": 180,
            "args": {"partition": partition}
        })

    activities.append({
        "name": "Aggregate",
        "path": "AggregateResults",
        "timeoutPerCellInSeconds": 120,
        "dependencies": [f"Process_{p}" for p in partitions]
    })

    return {"activities": activities, "concurrency": 25}

partitions = ["2024-01", "2024-02", "2024-03", "2024-04"]
dag = create_fan_out_dag(partitions)

results = notebookutils.notebook.runMultiple(dag)

Memvalidasi DAG

Gunakan validateDAG() untuk memverifikasi bahwa struktur DAG Anda valid sebelum eksekusi. Ini mendeteksi masalah seperti nama aktivitas yang duplikat, ketergantungan yang hilang, dan referensi melingkar.

notebookutils.notebook.validateDAG(DAG)

notebookutils.notebook.validateDAG(dag)

notebookutils.notebook.validateDAG(DAG)

Mengembalikan nilai

Metode mengembalikan validateDAG()True jika struktur DAG valid atau menimbulkan pengecualian jika validasi gagal.

Tip

Selalu panggil validateDAG() sebelumnya runMultiple() dalam alur kerja produksi untuk menangkap kesalahan struktural lebih awal.

Penanganan kegagalan runMultiple

Metode runMultiple() tersebut mengembalikan sebuah dict di mana setiap kunci adalah nama aktivitas dan setiap nilai berisi exitVal (string) serta exception (objek kesalahan atau None). Anda dapat memeriksa hasil parsial bahkan ketika beberapa aktivitas gagal:

from notebookutils.common.exceptions import RunMultipleFailedException

try:
    results = notebookutils.notebook.runMultiple(DAG)
except RunMultipleFailedException as ex:
    results = ex.result

for activity_name, result in results.items():
    if result["exception"]:
        print(f"{activity_name} failed: {result['exception']}")
    else:
        print(f"{activity_name} succeeded: {result['exitVal']}")

Pertimbangan

Tingkat paralelisme dari penjalankan beberapa notebook dibatasi oleh total sumber daya komputasi yang ada dari sesi Spark.
Jumlah default notebook bersamaan adalah 3 kali jumlah inti CPU yang tersedia. Anda dapat menyesuaikan nilai ini, tetapi paralelisme yang berlebihan dapat menyebabkan masalah stabilitas dan performa karena penggunaan sumber daya komputasi yang tinggi. Jika masalah muncul, pertimbangkan untuk memisahkan notebook menjadi beberapa runMultiple panggilan atau mengurangi tingkat konkurensi dengan menyesuaikan bidang konkurensi dalam parameter DAG.
Batas waktu default untuk seluruh DAG adalah 12 jam, dan batas waktu default untuk setiap sel dalam buku catatan anak adalah 90 detik. Anda dapat mengubah batas waktu dengan mengatur bidang timeoutInSeconds dan timeoutPerCellInSeconds di parameter DAG.
Konfigurasikan retry dan retryIntervalInSeconds untuk aktivitas yang mungkin gagal karena masalah sementara seperti batas waktu jaringan atau tidak tersedianya layanan sementara.
Notebook paralel berbagi sumber daya komputasi dalam satu sesi Spark. Monitor pemanfaatan sumber daya untuk menghindari tekanan memori dan kontensi CPU.

Keluar dari notebook

Metode exit() menyelesaikan sebuah notebook dengan sebuah nilai. Anda bisa menjalankan panggilan fungsi nesting di notebook secara interaktif atau dalam alur.

Saat Anda memanggil fungsi exit() dari notebook secara interaktif, notebook Fabric menghasilkan pengecualian, melewatkan eksekusi sel berikutnya, dan menjaga sesi Spark tetap hidup.
Saat Anda mengatur sebuah buku catatan dalam alur yang memanggil fungsi exit(), aktivitas buku catatan akan menghasilkan nilai keluar. Ini menyelesaikan eksekusi alur dan menghentikan sesi Spark.
Saat Anda memanggil fungsi exit() dalam notebook referensi, Fabric Spark menghentikan eksekusi notebook tersebut dan melanjutkan menjalankan sel berikutnya di notebook utama yang memanggil fungsi run(). Misalnya: Notebook1 memiliki tiga sel dan memanggilexit() fungsi di sel kedua. Notebook2 memiliki lima sel dan memanggil run(notebook1) di sel ketiga. Saat Anda mengeksekusi Notebook2, Notebook1 berhenti di sel kedua ketika mencapai fungsi exit(). Notebook2 terus menjalankan sel keempat dan sel kelimanya.

notebookutils.notebook.exit("value string")

notebookutils.notebook.exit("value string")

notebookutils.notebook.exit("value string")

Perilaku Pengembalian

Metode exit() ini tidak mengembalikan nilai. Ini mengakhiri buku catatan saat ini dan meneruskan string yang disediakan ke buku catatan atau pipeline yang memanggilnya.

Nota

Fungsi exit() menimpa output sel saat ini. Untuk menghindari kehilangan output pernyataan kode lain, panggil notebookutils.notebook.exit() di sel terpisah.

Penting

Jangan memanggil notebookutils.notebook.exit() di dalam blok try-catch. Pintu keluar tidak akan berlaku saat dibungkus dalam penanganan pengecualian. Panggilan exit() harus berada di tingkat atas kode Anda agar berfungsi dengan benar.

Contohnya:

Buku catatan Sample1 memiliki dua sel berikut:

Sel 1 menentukan parameter input dengan nilai default yang diatur ke 10.
sel 2 keluar dari notebook dengan input sebagai nilai keluar.

Anda bisa menjalankan Sample1 di notebook lain dengan nilai default:

exitVal = notebookutils.notebook.run("Sample1")
print (exitVal)

Hasil:

Anda bisa menjalankan Sample1 di notebook lainnya dan mengatur nilai input sebagai 20:

exitVal = notebookutils.notebook.run("Sample1", 90, {"input": 20 })
print (exitVal)

Hasil:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-02

NotebookUtils eksekusi buku catatan dan orkestrasi

Rujuk buku catatan

Mengembalikan nilai

Menyiapkan buku catatan anak untuk menerima parameter

Pertimbangan

Referensi menjalankan beberapa buku catatan secara paralel

Jalankan daftar notebook sederhana

Mengembalikan nilai

Menjalankan buku catatan dengan struktur DAG

Referensi parameter DAG

Nilai keluaran referensi antar aktivitas

Membangun DAG dinamis

Memvalidasi DAG

Mengembalikan nilai

Penanganan kegagalan runMultiple

Pertimbangan

Keluar dari notebook

Perilaku Pengembalian

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: