Mengelola dan menjalankan notebook di Fabric dengan API

Microsoft Fabric REST API menyediakan titik akhir layanan untuk operasi buat, baca, perbarui, dan hapus (CRUD) item Fabric. Artikel ini menjelaskan REST API notebook yang tersedia dan penggunaannya.

Dengan API notebook, teknisi data dan ilmuwan data dapat mengotomatiskan alur mereka sendiri dan membangun CI/CD dengan mudah dan efisien. API ini juga memudahkan pengguna untuk mengelola dan memanipulasi item notebook Fabric, dan mengintegrasikan notebook dengan alat dan sistem lain. Notebook dapat diorkestrasi dari alur Fabric dan penjadwal eksternal melalui API ini, memungkinkan integrasi yang mulus dengan alur kerja otomatis.

Tindakan manajemen Item ini tersedia untuk buku catatan:

Tindakan Deskripsi
Buat item Membuat buku catatan di dalam ruang kerja.
Perbarui item Memperbarui metadata buku catatan.
Memperbarui definisi item Memperbarui konten buku catatan.
Hapus item Menghapus buku catatan.
Dapatkan elemen Mengambil metadata dari notebook.
Memperoleh definisi item Mendapatkan konten buku catatan.
Daftar item Mencantumkan semua item di ruang kerja.

Untuk informasi selengkapnya, lihat Item - REST API.

Tindakan Penjadwal pekerjaan berikut ini dapat digunakan pada buku catatan:

Tindakan Deskripsi
Jalankan Item Job sesuai permintaan Jalankan notebook sesuai permintaan dengan dukungan untuk parameterisasi, konfigurasi sesi (seperti pengaturan Spark/komputasi), pemilihan lingkungan dan runtime, dan pemilihan target Fabric Lakehouse.
Batalkan Instans Pekerjaan Item Batalkan eksekusi pekerjaan buku catatan.
Dapatkan Instans Pekerjaan Item Peroleh status run buku catatan dan ambil nilai keluaran yang dikembalikan oleh run tersebut.

Untuk informasi selengkapnya, lihat Penjadwal Pekerjaan.

Catatan

Autentikasi prinsipal layanan didukung untuk Item REST API (operasi CRUD notebook) dan API Penjadwal Pekerjaan (eksekusi, pemantauan, dan pembatalan). Ini memungkinkan otomatisasi tanpa pengawasan yang aman dan skenario CI/CD. Tambahkan perwakilan layanan ke ruang kerja dengan peran yang sesuai (Admin, Anggota, atau Kontributor) untuk mengelola dan menjalankan buku catatan.

Nilai keluaran dari pelaksanaan buku catatan

Notebook yang dijalankan melalui API Penjadwal Pekerjaan dapat mengembalikan nilai keluar (exit value) yang dapat Anda gunakan untuk pengaturan alur kerja bersyarat. Nilai keluar muncul di exitValue bidang dalam payload respons Get Item Job Instance.

Buku catatan dapat mengatur nilai keluarnya dengan memanggil mssparkutils.notebook.exit("your-value") sebelum eksekusi selesai. Nilai keluar adalah string dan dapat mengodekan sinyal hasil apa pun—misalnya, , "success""no_rows_processed", atau hasil serial JSON.

Orkestrator eksternal, pipeline Fabric, dan alat otomatisasi lainnya dapat memanggil Get Item Job Instance setelah eksekusi selesai untuk membaca kode keluar dan menggunakan hasil untuk menentukan cabang. Contohnya:

  1. Kirim Pekerjaan Item Yang Dijalankan sesuai permintaan dengan parameter dan pengaturan eksekusi.
  2. Polling Dapatkan Instans Pekerjaan Item hingga status (Completedatau Failed).
  3. Baca exitValue dari respons untuk menentukan langkah berikutnya dalam alur kerja Anda.

Pola ini memungkinkan orkestrasi bersyarat dan sinyal hilir berdasarkan hasil eksekusi notebook.

Contoh ujung-ke-ujung

Contoh berikut menunjukkan cara menjalankan buku catatan dan memeriksa status serta nilai keluaran. Untuk skema isi permintaan lengkap, termasuk parameter, konfigurasi sesi, dan bidang pilihan Lakehouse, lihat referensi Job Scheduler - Run on demand Item Job API.

Langkah 1: Kirim perintah

Gunakan titik akhir Jalankan Pekerjaan Item sesuai permintaan untuk memulai eksekusi buku catatan:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances?jobType=RunNotebook

Respon mengembalikan 202 Accepted dengan header Location yang berisi URL dari instans pekerjaan yang Anda gunakan untuk memantau eksekusi.

Langkah 2: Mengambil status eksekusi dan nilai keluar

Gunakan URL dari Location header untuk memeriksa status dan membaca nilai keluar setelah eksekusi selesai:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances/{jobInstanceId}

Contoh respons (disingkat):

{
  "id": "<jobInstanceId>",
  "itemId": "<notebookId>",
  "jobType": "RunNotebook",
  "invokeType": "OnDemand",
  "status": "Completed",
  "startTimeUtc": "2026-03-01T10:00:00Z",
  "endTimeUtc": "2026-03-01T10:05:00Z",
  "failureReason": null,
  "exitValue": "success"
}

Baca exitValue untuk menentukan hasil dan cabang logika otomatisasi Anda yang sesuai.

  • Last updated on