Cari dan jelajahi item dengan katalog OneLake dan REST API Fabric

Katalog OneLake di Microsoft Fabric memungkinkan Anda menemukan dan menjelajahi item-item data di seluruh tenant Anda. Artikel ini memperlihatkan cara mereplikasi pengalaman Jelajahi katalog secara terprogram, dimulai dengan pencarian lalu menggunakan pengidentifikasi item dari hasil Anda untuk mengambil metadata, tag, dan informasi tabel terperinci.

Alur kerja API katalog OneLake yang khas

Pola umum untuk menjelajahi item melalui API mengikuti alur yang sama dengan UI katalog:

Pencarian — Temukan item di seluruh penyewa menggunakan pencarian teks lengkap atau telusuri berdasarkan ruang kerja.
Dapatkan detail item — Gunakan GUID item dan tipe dari hasil Anda untuk mengambil metadata umum dengan Ambil Item, lalu panggil endpoint Get khusus tipe untuk properti lainnya seperti string koneksi atau URI layanan.
Jelajahi koneksi dan pintasan — Ketahui sumber data apa yang terhubung ke item dengan Daftar Koneksi Item, dan untuk item OneLake, buat pemetaan referensi data eksternal dengan Daftar Pintasan.
Jelajahi tabel — Untuk item data seperti lakehouse, gudang, dan database cermin, telusuri skema dan tabel menggunakan ONELake Table API.

Bagian berikut menjelaskan setiap langkah dan API yang terlibat.

Cari barang

API Pencarian Katalog adalah titik masuk utama untuk menemukan item di seluruh penyewa Anda. Ini menyediakan pencarian teks lengkap yang mirip dengan bilah pencarian di antarmuka pengguna katalog OneLake.

API mendukung:

Pencarian teks lengkap — Cari berdasarkan nama item, deskripsi, atau nama ruang kerja.
Filter — Persempit hasil menurut jenis item.

Hasil pencarian mengembalikan pengidentifikasi item (GUID), nama, deskripsi, jenis, dan informasi ruang kerja. Gunakan pengidentifikasi ini dengan API yang dijelaskan di bagian berikut untuk mendapatkan detail yang lebih kaya tentang setiap hasil.

Contoh: Cari Lakehouses

POST https://api.fabric.microsoft.com/v1/catalog/search
Content-Type: application/json

{
  "search": "Sales Revenue",
  "pageSize": 50,
  "filter": "Type eq 'Lakehouse'"
}

Respon mencakup array item yang cocok, masing-masing dengan id (GUID) dan workspaceId yang Anda dapat gunakan dalam panggilan API berikutnya.

Menelusuri item dan ruang kerja

Jika Anda tidak memerlukan pencarian teks lengkap, Anda dapat menelusuri hierarki katalog secara langsung:

Mencantumkan Ruang Kerja — Mengembalikan ruang kerja yang dapat Anda akses. Setiap ruang kerja dalam respons menyertakan domainId properti jika ruang kerja ditetapkan ke domain.
Item Daftar — Mengembalikan item di ruang kerja tertentu.

Titik akhir ini mengembalikan pengidentifikasi item yang sama dengan yang Anda dapatkan dari pencarian, sehingga Anda dapat menggunakannya sebagai titik awal alternatif untuk alur penelusuran paling detail yang dijelaskan dalam artikel ini. Jika ruang kerja milik domain, Anda dapat menyelesaikan nama domain menggunakan API Get Domain.

Dapatkan detail item

Setelah Anda memiliki pengidentifikasi item dari hasil pencarian, gunakan Get Item API untuk mengambil metadata umum:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}

Responsnya meliputi:

Nama, jenis, dan deskripsi item
ID dan nama ruang kerja
Status dukungan (Data Yang Dipromosikan, Disertifikasi, atau Master)
Tag yang ditetapkan ke item (lihat TAG API untuk manajemen tag terprogram)

Mendapatkan properti item khusus jenis

Get Item API generik mengembalikan metadata umum yang dibagikan oleh semua jenis item. Banyak jenis item juga memiliki titik akhir Get sendiri yang mengembalikan lebih banyak properti—seperti string koneksi, URI layanan, dan jalur OneLake—yang perlu Anda sambungkan atau kerjakan dengan item.

Pola URL untuk endpoint khusus jenis adalah:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/{itemTypePlural}/{itemId}

Jenis item berikut mengembalikan properti tambahan di luar apa yang disediakan Get Item API generik:

Tipe barang	Properti tambahan	Referensi API
Lingkungan	Terbitkan detail (status, pustaka/status pengaturan Spark)	Dapatkan Lingkungan
Eventhouse	URI layanan kueri, URI layanan pemasukan data, ID database KQL anak	Dapatkan Eventhouse
KQL Database	ID eventhouse induk, URI layanan kueri/penyerapan, jenis database	Dapatkan KQL Database
Lakehouse	Jalur tabel/berkas OneLake, string koneksi titik akhir SQL, skema default	Dapatkan Lakehouse
Database yang dicerminkan	Jalur tabel OneLake, string koneksi titik akhir SQL, skema default	Dapatkan Database Tercermin
Eksperimen ML	ID eksperimen MLflow	Dapatkan Eksperimen ML
Definisi kerja Spark	Jalur akar OneLake	Mendapatkan Definisi Pekerjaan Spark
database SQL	string koneksi SQL, server FQDN, nama database, retensi cadangan, titik pemulihan	Mendapatkan SQL Database
Warehouse	SQL string koneksi, tanggal pembuatan, jenis penyortiran	Dapatkan Gudang

Jenis item lainnya juga memiliki endpoint Get khusus tipe, tetapi saat ini mengembalikan metadata yang sama dengan API Get Item generik. Jenis item tersebut termasuk Detektor Anomali, Apache Airflow Job, Copy Job, Data Pipeline, Eventstream, GraphQL API, KQL Dashboard, KQL Queryset, ML Model, Mounted Data Factory, Notebook, Reflex, Report, dan Semantic Model.

Daftar koneksi item

Untuk melihat sumber data apa yang terhubung dengan suatu item, gunakan API Daftar Koneksi Item:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/connections

Respons mencakup setiap jenis koneksi (seperti SQL atau Web), jenis konektivitas (cloud, gateway lokal, atau gateway jaringan virtual), dan nama tampilan. Ini berguna untuk memahami dependensi item—misalnya, ke titik akhir SQL mana sebuah model semantik terhubung melalui Direct Lake, atau sumber eksternal mana yang diakses oleh pipa data.

Note

Koneksi Item Daftar memerlukan izin baca dan tulis pada item, yang merupakan tingkat izin yang lebih tinggi daripada API Dapatkan Item baca-saja.

Daftar pintasan OneLake

Untuk item yang disimpan di OneLake, seperti lakehouse, pintasan adalah mekanisme utama untuk mereferensikan data eksternal. API Daftar Pintasan mengungkapkan dari mana data berasal:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/shortcuts

Setiap pintasan dalam respons mencakup jalurnya dalam item, jenis target (OneLake, ADLS Gen2, Amazon S3, Google Cloud Storage, S3 Compatible, Dataverse, atau External Data Share), dan detail lokasi target. Informasi ini membantu Anda memetakan lanskap data lengkap item, termasuk tabel lokal dan referensi eksternal.

Menjelajahi tabel dalam item

Halaman detail item katalog memperlihatkan tabel dan skema untuk item data seperti lakehouse dan gudang. Dengan menggunakan ID ruang kerja dan ID item yang Anda dapatkan dari hasil pencarian atau Dapatkan Item, Anda dapat menggunakan API Tabel OneLake untuk menjelajahi informasi yang sama ini secara terprogram.

API Tabel disajikan di titik akhir khusus:

https://onelake.table.fabric.microsoft.com

Dua ragam protokol tersedia di titik akhir ini. Pilih berdasarkan ekosistem dan alat Anda: Iceberg REST Catalog (IRC) dan Delta. Kedua protokol memerlukan ID ruang kerja dan ID item untuk mencakup permintaan. GUID ini berasal dari hasil pencarian atau Get Item.

Jika item data tidak mendukung skema (seperti lakehouse yang tidak mendukung skema), kedua protokol mengembalikan skema default dbo .

Operations

Pengoperasian	Delta	Iceberg
Dapatkan konfigurasi	—	`GET /iceberg/v1/config?warehouse={workspaceId}/{itemId}`
Mencantumkan skema	`GET /delta/{workspaceId}/{itemId}/api/2.1/unity-catalog/schemas`	`GET /iceberg/v1/{prefix}/namespaces`
Daftar tabel	`GET /delta/{workspaceId}/{itemId}/api/2.1/unity-catalog/tables`	`GET /iceberg/v1/{prefix}/namespaces/{schema}/tables`
Dapatkan tabel	`GET /delta/{workspaceId}/{itemId}/api/2.1/unity-catalog/tables/{table}`	`GET /iceberg/v1/{prefix}/namespaces/{schema}/tables/{table}`

Semua jalur relatif terhadap https://onelake.table.fabric.microsoft.com. Protokol Iceberg memerlukan pemanggilan "Get config" terlebih dahulu untuk mendapatkan {prefix}, yang digunakan dalam permintaan berikutnya.

Contoh: Menampilkan tabel di lakehouse dari hasil pencarian

Setelah mencari informasi lakehouse dan mendapatkan workspaceId dan id-nya, Anda dapat mencantumkan tabelnya dengan menggunakan salah satu dari protokol berikut:

# Step 1: Get the Iceberg config prefix
GET https://onelake.table.fabric.microsoft.com/iceberg/v1/config?warehouse={workspaceId}/{itemId}

# Step 2: List tables in the default schema
GET https://onelake.table.fabric.microsoft.com/iceberg/v1/{prefix}/namespaces/dbo/tables