Tutorial: Menjalankan item Fabric menggunakan APACHE Airflow DAGs

Catatan

Pekerjaan Apache Airflow didukung oleh Apache Airflow.

Dalam tutorial ini, Anda membangun graf berarah asiklik (DAG) untuk menjalankan item Microsoft Fabric, termasuk:

Notebooks
Definisi pekerjaan spark
Rantai Pengolahan
Model Semantik
Fungsi data pengguna

Prasyarat

Untuk memulai, Anda harus menyelesaikan prasyarat berikut:

Catatan

Pastikan pekerjaan Apache Airflow tersedia di wilayah kapasitas yang Anda gunakan untuk ruang kerja Anda. Untuk informasi selengkapnya, lihat wilayah kapasitas yang tersedia.

Buat aplikasi ID Microsoft Entra jika Anda tidak memilikinya.
Akun admin tingkat penyewa harus mengaktifkan pengaturan 'Izinkan persetujuan pengguna untuk aplikasi'. Untuk mengonfigurasi pengaturan persetujuan pengguna melalui pusat admin Microsoft Entra:
1. Masuk ke Pusat Admin Microsoft Entra sebagai Peran Istimewa Administrator.
2. Telusuri ke Identitas>Aplikasi>Aplikasi Perusahaan>Persetujuan dan izin>Pengaturan persetujuan pengguna.
3. Pada Persetujuan pengguna untuk aplikasi, pilih pengaturan persetujuan mana yang ingin Anda konfigurasikan untuk semua pengguna.
4. Pilih Simpan untuk menyimpan pengaturan Anda.
Untuk informasi selengkapnya, Lihat: Mengonfigurasi persetujuan pengguna
Pastikan bahwa akun yang digunakan untuk menghasilkan token refresh memiliki izin kontributor pada ruang kerja yang berisi alur dan buku catatan.
Aktifkan Pemicu dalam alur kerja data untuk memungkinkan penggunaan operator yang dapat ditangguhkan.

Plugin Apache Airflow

Untuk memicu eksekusi item Microsoft Fabric sesuai permintaan, tutorial ini menggunakan apache-airflow-microsoft-fabric-plugin yang telah diinstal sebelumnya dalam persyaratan pekerjaan Apache Airflow.

Autentikasi

Untuk memanggil API Microsoft Fabric, aplikasi harus mendapatkan token akses dari platform identitas Microsoft. Token akses ini mencakup informasi tentang apakah aplikasi berwenang untuk mengakses item Microsoft Fabric atas nama pengguna yang masuk atau dengan identitasnya sendiri. Bagian ini menyediakan permintaan HTTP mentah yang terlibat untuk aplikasi guna mendapatkan akses atas nama pengguna menggunakan alur populer yang disebut alur pemberian kode otorisasi OAuth 2.0.

Anda harus menyelesaikan langkah-langkah berikut untuk mendapatkan token refresh, yang nantinya akan digunakan dalam koneksi Apache Airflow:

Minta otorisasi.
Meminta token akses dan token refresh.

Sebelum melanjutkan langkah-langkah dalam artikel ini, Simpan nilai berikut dari pendaftaran aplikasi yang Anda buat awalnya:

ID Klien: Pengidentifikasi unik untuk aplikasi Anda yang ditetapkan oleh platform identitas Microsoft.
Rahasia Klien: (Opsional) Kata sandi yang digunakan aplikasi Anda untuk mengautentikasi dengan platform identitas Microsoft. Properti ini tidak diperlukan untuk klien publik seperti aplikasi bawaan, aplikasi seluler, dan aplikasi laman tunggal.
ID Penyewa: Pengidentifikasi unik untuk penyewa Anda di platform identitas Microsoft.
URI/URL Pengalihan: Titik akhir tempat aplikasi Anda menerima respons dari Platform Identitas Microsoft. Dalam langkah-langkah ini, Anda menerima kode otorisasi di URI pengalihan terdaftar.

Langkah 1: Meminta otorisasi

Titik Akhir otorisasi

Langkah pertama dalam alur kode otorisasi adalah agar pengguna mengotorisasi aplikasi untuk bertindak atas nama mereka. Dengan mengirim permintaan 'GET' ke titik akhir '/otorisasi', MICROSOFT Entra ID memasukkan pengguna dan meminta persetujuan mereka untuk izin yang diminta aplikasi. Ganti placeholder dengan nilai Anda dan tempel URL berikut ini di browser Anda.

Plugin memerlukan cakupan berikut untuk autentikasi:

itemType.Execute.All (misalnya: Notebook.Execute.All, Pipeline.Execute.All): Memanggil Aplikasi diizinkan untuk menjalankan semua item '<itemtype>' yang dapat diakses pengguna.
itemType.Read.All (misalnya: Notebook.Execute.All, Pipeline.Execute.All): Aplikasi panggilan diizinkan untuk membaca semua item jenis '<itemType>' yang dapat diakses pengguna.
offline_access: Cakupan OIDC standar diperlukan agar aplikasi dapat memperoleh token refresh. Aplikasi ini dapat menggunakan token refresh untuk mendapatkan token akses baru saat token saat ini kedaluwarsa.

// Line breaks for legibility only
// This request uses Item.Execute.All, Item.Read.All and offline_access scopes. You can update them as per your requirements.


https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id={client_id}
&response_type=code
&redirect_uri={redirect_uri}
&response_mode=query
&scope=https%3A%2F%2Fapi.fabric.microsoft.com%2FItem.Execute.All%20https%3A%2F%2Fapi.fabric.microsoft.com%2FItem.Read.All%20offline_access 
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Untuk mengetahui selengkapnya tentang parameter, lihat Meminta kode otorisasi.

Setelah aplikasi mengirim permintaan otorisasi, pengguna diminta untuk memasukkan kredensial mereka untuk mengautentikasi dengan Microsoft. Titik akhir platform identitas Microsoft v2.0 memastikan bahwa pengguna menyetujui izin yang ditunjukkan dalam parameter kueri cakupan. Cuplikan layar berikut adalah contoh kotak dialog persetujuan yang disajikan untuk pengguna akun Microsoft.

Respons otorisasi

Jika pengguna menyetujui izin yang diminta oleh aplikasi, platform identitas Microsoft mengirim kode otorisasi ke URI pengalihan aplikasi. Berikut adalah contoh respons yang berhasil terhadap permintaan sebelumnya. Karena parameter response_mode dalam permintaan diatur ke kueri, respons dikembalikan dalam string kueri URL pengalihan. Untuk langkah berikutnya, salin nilai 'kode' dari respons.

HTTP/1.1 200 OK

https://localhost/myapp/?
code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d...
&state=12345
&session_state=fe1540c3-a69a-469a-9fa3-8a2470936421#

Langkah 2: Meminta token akses

Aplikasi ini menggunakan kode otorisasi yang diterima pada langkah sebelumnya untuk meminta token akses dengan mengirim permintaan POST ke /token titik akhir. Pastikan cakupan dan redirect_uri Anda cocok dengan nilai yang Anda gunakan di langkah sebelumnya. Anda dapat menempelkan permintaan berikut di alat seperti Insomnia untuk mengirim permintaan.

// Line breaks for legibility only
// This request uses Item.Execute.All, Item.Read.All and offline_access scopes. You can update them as per your requirements.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id={client_id}
&scope=https%3A%2F%2Fapi.fabric.microsoft.com%2FItem.Execute.All%2FItem.Read.All%20offline_access
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri={redirect_uri}
&grant_type=authorization_code
&code_verifier=WuiPvLwjYU6ehi--Gv5P58u7NOd4dJgE8BSQzZ-7nT3xq4OrVp2cxADyUvYJqkH2sfLhPjuqUCbbbk4x11cfzLCKADIE8mht3vwyGoSL7DnMhC4SFAunOx_mJ99hVeKh
&client_secret={client_secret}   // NOTE: (Optional) Only required for web apps.

Untuk mengetahui selengkapnya tentang parameter, lihat Meminta token akses.

Respon token akses

Token akses berisi daftar izin yang berlaku untuk token akses dalam cakupan parameter. Responsnya mirip dengan sampel berikut. Salin nilai 'refresh_token' dari respons untuk digunakan dalam koneksi Apache Airflow.

HTTP/1.1 200 OK
Content-type: application/json

{
    "token_type": "Bearer",
    "scope": "Mail.Read User.Read",
    "expires_in": 3736,
    "ext_expires_in": 3736,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}

Menyiapkan koneksi Apache Airflow

Koneksi Apache Airflow digunakan untuk menyimpan kredensial yang diperlukan untuk mengautentikasi dengan API Microsoft Fabric. Anda dapat menyiapkan koneksi dengan 2 cara.

UI pekerjaan Apache Airflow Fabric

Pada bilah Beranda , klik Tambahkan koneksi.
Pop-up akan terbuka untuk membantu Anda menyiapkan koneksi Apache Airflow Fabric Anda. Ikuti instruksi dan tambahkan detail berikut:
- ID Koneksi: Nama ID Koneksi.
- Deskripsi: Deskripsi koneksi
- Endpoint: Titik akhir Fabric API Anda. Contoh. "https://api.fabric.microsoft.com"
- ID Penyewa: ID Penyewa Anda
- ID Klien: ID klien aplikasi Anda yang ditetapkan ke aplikasi Anda.
- Rahasia klien: Rahasia klien pendaftaran aplikasi Anda.
Klik Buat setelah Anda mengisi semuanya.

UI aliran udara Apache

Navigasi ke "Lihat koneksi Airflow" untuk menambahkan koneksi Apache Airflow baru.
Tambahkan koneksi baru dan isi detail berikut:
- ID Koneksi: Nama ID Koneksi.
- Jenis Koneksi: Generik
- Masuk: ID Aplikasi (klien) yang ditetapkan untuk aplikasi Anda.
- Kata sandi: Token refresh diambil di langkah sebelumnya.
- Ekstra: Bidang ini berisi parameter berikut:
  - tenantId: (Wajib) Nilai {tenant} di jalur permintaan dapat digunakan untuk mengontrol siapa yang dapat masuk ke aplikasi.
  - clientSecret: (Opsional, hanya diperlukan untuk aplikasi web) Rahasia klien pendaftaran aplikasi.
  - cakupan: (Wajib) String cakupan yang dipisahkan spasi yang diperlukan aplikasi untuk mengakses API Microsoft Fabric.
  Salin format objek json berikut, perbarui nilai, hapus komentar dan tempelkan di bidang Ekstra.
```
{
    "tenantId": "{tenant}",
    "scopes": "https://api.fabric.microsoft.com/Item.Execute.All https://api.fabric.microsoft.com/Item.Read.All offline_access",
    "clientSecret": "{client-secret}" // (Optional) NOTE: Only required for web apps.
}
```
Pilih Simpan.

Buat DAG untuk menjalankan item Microsoft Fabric

Di kanvas pekerjaan Apache Airflow Anda, ada 3 ubin. Pilih Jalankan artefak Run Fabric. Ini akan membuka pop-up baru.

Pilih Koneksi Fabric Anda menggunakan menu tarik-turun. Jika Anda belum membuat koneksi, klik + untuk menambahkan koneksi Fabric baru.
Kemudian, pilih ruang kerja Anda menggunakan daftar drop-down.
Pilih jenis artefak mana yang ingin Anda jalankan. Anda dapat memilih dari:

Notebook
Definisi kerja Spark
Pipeline
Model Semantik
Fungsi data pengguna

Kemudian, pilih artefak yang ingin Anda jalankan.
Beri nama DAG Anda lalu konfigurasikan waktu habis maksimum Anda dan apakah Anda ingin mengaktifkan eksekusi Yang Dapat Ditangguhkan.
Klik Buat. Ini akan membuka DAG baru di editor untuk Anda tinjau dan edit. Kemudian, Anda dapat menyimpan perubahan dan menjalankan DAG.

Buat file DAG baru di folder 'dags' di penyimpanan terkelola Fabric dengan kode berikut. Ganti tempat penampung berikut:

fabric_conn_id: ID koneksi yang Anda buat di langkah sebelumnya.
workspace_id: ID ruang kerja tempat item berada.
item_id: ID item yang ingin Anda jalankan. Misalnya, ID Notebook atau ID Alur.
job_type: Jenis item yang ingin Anda jalankan. Misalnya, untuk buku catatan gunakan "RunNotebook", untuk Definisi Pekerjaan Spark gunakan "sparkjob" dan untuk pipeline gunakan "Pipeline". Bagian ini peka terhadap huruf besar/kecil.
wait_for_termination: Jika diatur ke True, operator menunggu item selesai sebelum melanjutkan ke tugas berikutnya.
deferrable: Jika diatur ke True, operator dapat membebaskan sumber daya sambil menunggu item selesai.

from airflow import DAG
from datetime import datetime
from apache_airflow_microsoft_fabric_plugin.operators.fabric import FabricRunItemOperator

with DAG(
  dag_id="Run_Fabric_Item",
  schedule_interval="@daily",
  start_date=datetime(2023, 8, 7),
  catchup=False,
) as dag:

  run_fabric_item = FabricRunItemOperator(
    task_id="run_fabric_item",
    fabric_conn_id="fabric_conn",
    workspace_id="<workspace_id>",
    item_id="<item_id>",
    job_type="<job_type>",
    wait_for_termination=True,
    deferrable=True,
  )

  run_fabric_item

Membuat file plugin untuk operator kustom

Jika Anda ingin menyertakan tautan pemantauan eksternal untuk item Microsoft Fabric berjalan, buat file plugin sebagai berikut:

Buat file baru di plugins folder dengan kode berikut:

   from airflow.plugins_manager import AirflowPlugin

   from apache_airflow_microsoft_fabric_plugin.hooks.fabric import FabricHook
   from apache_airflow_microsoft_fabric_plugin.operators.fabric import FabricRunItemLink

   class AirflowFabricPlugin(AirflowPlugin):
      """
      Microsoft Fabric plugin.
      """

      name = "fabric_plugin"
      operator_extra_links = [FabricRunItemLink()]
      hooks = [
          FabricHook,
      ]

Memantau DAG Anda

Di Antarmuka Pengguna Pekerjaan Apache Airflow

Saat Anda membuka file DAG di Fabric Managed Storage, "Hasil" muncul di bagian bawah. Pilih panah untuk melihat hasil eksekusi DAG.

Di Apache Airflow UI

Buka UI Airflow dan pilih DAG yang Anda buat.
Jika Anda menambahkan plugin, Anda akan melihat tautan pemantauan eksternal. Pilih di atasnya untuk menavigasi ke item yang dijalankan.
Integrasi Xcom: Picu DAG untuk melihat output tugas di tab Xcom.

Mulai Cepat: Membuat pengaturan ruang kerja Pekerjaan Apache Airflow Job Apache Airflow

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-16