Mengaktifkan federasi katalog OneLake

Penting

Artikel ini memperlihatkan cara membaca data di OneLake menggunakan federasi katalog. Ini memungkinkan kueri Katalog Unity dijalankan langsung pada penyimpanan OneLake.

Federasi OneLake memungkinkan Anda menganalisis data yang disimpan di Lakehouse atau Warehouse tanpa menyalinnya, membawa analitik yang kuat dan kemampuan AI/BI di Azure Databricks langsung ke data OneLake Anda. Akses data bersifat baca-saja.

Sebelum Anda mulai

Anda harus memenuhi persyaratan berikut untuk menjalankan kueri federasi di OneLake menggunakan federasi katalog:

Persyaratan ruang kerja:

Workspace telah diaktifkan untuk Unity Catalog.

Persyaratan komputasi:

Konektivitas jaringan dari sumber daya komputasi Anda ke sistem database target. Lihat Rekomendasi jaringan untuk Lakehouse Federation.
Komputasi Azure Databricks harus menggunakan Databricks Runtime 18.0 atau lebih tinggi dan mode akses standar.
Gudang SQL harus menggunakan 2025.40 atau lebih tinggi.

Izin diperlukan:

Untuk membuat koneksi, Anda harus menjadi admin metastore atau pengguna yang memiliki hak istimewa CREATE CONNECTION dan CREATE STORAGE CREDENTIAL pada metastore Unity Catalog yang terhubung ke ruang kerja.
Untuk membuat katalog asing, Anda harus memiliki izin CREATE CATALOG di metastore dan menjadi pemilik koneksi atau memiliki hak istimewa CREATE FOREIGN CATALOG pada koneksi.

Persyaratan izin tambahan dinyatakan di setiap bagian berbasis tugas berikut.

Anda harus memiliki izin untuk membuat sumber daya di Azure, mengonfigurasi akses di Fabric, dan mengelola Unity Catalog di Azure Databricks.
Metode autentikasi yang didukung:
- Azure Managed Identity melalui Konektor Akses untuk Azure Databricks
- Prinsipal layanan Azure

Pengaturan penyewa fabric dan ruang kerja:

Administrator Fabric harus mengaktifkan prinsipal layanan dapat menggunakan API Fabric dalam pengaturan penyewa. Ini memungkinkan identitas terkelola dan perwakilan layanan untuk mengautentikasi dengan Fabric. Untuk informasi selengkapnya, lihat Pengaturan penyewa prinsipal layanan.
Administrator Fabric harus mengaktifkan pengaturan penyewa Izinkan aplikasi yang berjalan di luar Fabric untuk mengakses data melalui OneLake. Ini memungkinkan Azure Databricks untuk terhubung ke penyimpanan OneLake. Untuk informasi selengkapnya, lihat Mengizinkan aplikasi yang berjalan di luar Fabric untuk mengakses data melalui OneLake.
Fabric Administrator harus mengaktifkan pengaturan penyewa Gunakan token SAS yang didelegasikan pengguna berumur pendek. Pengaturan ini memungkinkan OneLake mengeluarkan token SAS berumur pendek yang didukung Entra yang Azure Databricks gunakan untuk membaca data OneLake. Untuk informasi selengkapnya, lihat Tanda tangan akses bersama OneLake.
Di ruang kerja Fabric yang berisi data Anda, Autentikasi dengan token SAS yang didelegasikan pengguna OneLake harus diaktifkan. Navigasi ke pengaturan ruang kerja>pengaturan yang didelegasikan>OneLake untuk mengaktifkan pengaturan ini.

Item data Fabric berikut didukung:

Fabric Lakehouse
Gudang Kain

Menyiapkan federasi katalog

Langkah-langkah berikut memandu Anda membuat koneksi dan katalog asing untuk federasi OneLake.

Langkah 1: Menyiapkan autentikasi Azure

Federasi OneLake mendukung dua metode autentikasi.

Azure Managed Identity (disarankan): Menggunakan Konektor Akses Databricks dengan identitas terkelola.
Azure Service Principal: Menggunakan aplikasi ID Microsoft Entra dengan kredensial klien. Metode ini mendukung autentikasi lintas penyewa, memungkinkan Databricks mengakses ruang kerja Fabric yang terletak di penyewa Azure yang berbeda.

Opsi A: Membuat konektor akses (Identitas Terkelola)

Konektor Akses Databricks membuat identitas terkelola yang digunakan Azure Databricks untuk mengautentikasi dengan OneLake.

Di Portal Microsoft Azure, cari dan buat Konektor Akses baru untuk sumber daya Azure Databricks .
Ikuti perintah untuk membuat konektor. Sumber daya ini membuat Identitas Terkelola yang diberikan oleh sistem.
Catat ID Sumber Daya konektor yang baru dibuat. Anda memerlukan ID ini saat membuat kredensial penyimpanan Katalog Unity.

ID sumber daya dalam format:
```
/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Databricks/accessConnectors/<connector-name>
```

Untuk informasi selengkapnya tentang membuat konektor akses dan menggunakan identitas terkelola, lihat Menggunakan identitas terkelola Azure di Unity Catalog untuk mengakses penyimpanan.

Opsi B: Mendaftarkan prinsipal layanan

Jika Anda lebih suka menggunakan perwakilan layanan alih-alih identitas terkelola:

Di Portal Microsoft Azure, navigasikan kependaftaran Aplikasi> Microsoft Entra dan daftarkan aplikasi baru (atau gunakan yang sudah ada).
Rekam ID Aplikasi (klien) dan ID Direktori (penyewa).
Di bawah Sertifikat & rahasia, buat rahasia klien baru dan catat nilai rahasia.

Langkah 2: Memberikan izin dalam Fabric

Berikan izin identitas terkelola atau perwakilan layanan untuk membaca data Fabric.

Dalam portal Fabric, buka ruang kerja yang berisi item data Lakehouse atau Warehouse Anda.
Di ruang kerja, klik ikon gigi Pengaturan ruang kerja , lalu klik Kelola akses.
Klik Tambahkan orang atau grup.
Cari dan pilih Identitas Terkelola atau prinsipal layanan. Untuk Identitas Terkelola, nama harus cocok dengan konektor akses yang Anda buat sebelumnya. Untuk perwakilan layanan, cari nama aplikasi yang Anda daftarkan.
Tetapkan identitas peran Anggota minimal. Anda juga dapat menetapkan peran Kontributor atau Admin .
Klik Tambahkan.
Verifikasi bahwa identitas muncul di daftar akses dengan peran yang sesuai. Izin pada masing-masing item Lakehouse dan Warehouse diwarisi dari peran di tingkat ruang kerja.

Langkah 3: Membuat kredensial penyimpanan

Buat kredensial penyimpanan di Katalog Unity yang mereferensikan identitas yang Anda konfigurasi di Langkah 1.

Di ruang kerja Azure Databricks Anda, klik Katalog.
Di bagian atas panel Katalog, klik dan pilih Buat kredensial dari menu.

Jika Anda menggunakan Identitas Terkelola:

Di modal Buat kredensial baru , untuk Jenis Kredensial, pilih Identitas Terkelola Azure.
Untuk Nama kredensial, masukkan Nama untuk kredensial penyimpanan (misalnya, onelake_storage_cred).
Untuk ID konektor Access, masukkan ID sumber daya konektor akses yang Anda buat sebelumnya.
(Opsional) Tambahkan komentar.
Klik Buat.

Jika Anda menggunakan Service Principal:

Anda tidak dapat membuat kredensial penyimpanan perwakilan layanan menggunakan Catalog Explorer. Anda harus menjadi admin akun Azure Databricks dan menggunakan STORAGE Credentials API. Contohnya:

curl -X POST -n \
https://<databricks-instance>/api/2.1/unity-catalog/storage-credentials \
-d '{
   "name": "<storage-credential-name>",
   "read_only": true,
   "azure_service_principal": {
      "directory_id": "<directory-id>",
      "application_id": "<application-id>",
      "client_secret": "<client-secret>"
   },
   "skip_validation": "false"
   }'

Anda juga dapat membuat kredensial penyimpanan menggunakan penyedia Terraform Databricks dan databricks_storage_credential.

Langkah 4: Membuat koneksi Katalog Unity

Buat koneksi Katalog Unity yang menggunakan kredensial penyimpanan untuk mengakses OneLake.

Eksplorer Katalog

Di ruang kerja Azure Databricks Anda, klik Katalog.
Di bagian atas panel Katalog , klik plus dan pilih Buat koneksi dari menu.
Pada halaman Dasar-dasar koneksi , masukkan Nama koneksi (misalnya, onelake_connection).
Pilih Jenis koneksiOneLake.
(Opsional) Tambahkan komentar.
Klik Berikutnya.
Pada halaman Detail koneksi , untuk Kredensial, pilih kredensial penyimpanan yang Anda buat di langkah sebelumnya (misalnya, onelake_storage_cred).
Untuk Ruang Kerja, masukkan ID ruang kerja untuk Ruang Kerja Fabric Anda.
Klik Buat koneksi.

SQL

Jalankan perintah berikut ini di buku catatan atau editor kueri Databricks SQL. Ganti nilai placeholder ini:

<connection-name>: Nama untuk koneksi.
<workspace-id>: GUID ruang kerja OneLake Anda.
<storage-credential-name>: Nama kredensial penyimpanan yang Anda buat di langkah 3.

CREATE CONNECTION <connection-name> TYPE onelake
OPTIONS (
  workspace '<workspace-id>',
  credential '<storage-credential-name>'
);

Langkah 5: Membuat katalog asing

Katalog asing menautkan item data Fabric tertentu ke katalog di Katalog Unity.

Memperoleh ID data item Fabric

Di portal Fabric, arahkan ke target Lakehouse atau Warehouse.
Salin ID Item Data, yang merupakan GUID (misalnya, f089354e-8366-4e18-aea3-4cb4a3a50b48).

Anda dapat menemukan GUID ini di UI Fabric atau dengan menyalinnya dari URL browser Anda saat Anda menavigasi ke Lakehouse atau Warehouse:
```
https://app.fabric.microsoft.com/groups/<workspace-id>/lakehouses/<data-item-id>?experience=power-bi
```

Membuat katalog

Eksplorer Katalog

Di ruang kerja Databricks Anda, klik Katalog.
Di bagian atas panel Katalog , klik plus dan pilih Buat katalog dari menu.
Pada dialog Buat katalog baru , masukkan nama untuk katalog (misalnya, fabric_sales).
Pilih JenisAsing.
Pilih Koneksi yang Anda buat di Langkah 4 (misalnya, onelake_connection).
Untuk Item data, masukkan ID item data yang Anda salin dari portal Fabric.
(Opsional) Klik Uji koneksi untuk memvalidasi konfigurasi Anda.
Klik Buat.

SQL

Jalankan perintah SQL berikut ini di notebook atau editor kueri Databricks SQL. Item dalam tanda kurung bersifat opsional. Ganti nilai placeholder ini:

<catalog-name>: Nama untuk katalog di Azure Databricks.
<connection-name>: Koneksi yang Anda buat di langkah 4.
<data-item-id>: GUID dari Fabric Lakehouse atau Gudang.

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (
  data_item '<data-item-id>'
);

Anda juga dapat menentukan parameter opsional berikut:

CREATE FOREIGN CATALOG <catalog-name> USING CONNECTION <connection-name>
OPTIONS (
  data_item '<data-item-id>',
  item_type 'Lakehouse',
  create_volume_for_lakehouse_files 'true'
);

item_type: Lakehouse (default) atau Warehouse.
create_volume_for_lakehouse_files: true (default) atau false. Ketika true, aplikasi ini membuat volume untuk folder Lakehouse /Files. Hanya berlaku untuk item Lakehouse. Lihat Mengakses data yang tidak terstruktur.

Katalog disinkronkan secara otomatis, membuat tabel Fabric segera tersedia.

Mengakses data yang tidak terstruktur

Federasi OneLake mendukung akses baca-saja ke data yang tidak terstruktur yang disimpan di folder /Files dari sebuah Lakehouse. Hal ini dicapai melalui volume-volume pada Unity Catalog.

Saat Anda membuat katalog asing dengan create_volume_for_lakehouse_files disetel ke true (default), volume secara otomatis dibuat di bawah skema onelake-folders. Volume ini menunjuk ke /Files folder Lakehouse dan menyediakan akses baca-saja ke file yang disimpan di sana.

Anda dapat menelusuri dan membaca file menggunakan jalur volume:

LIST '/Volumes/<catalog-name>/onelake-folders/files/';

df = spark.read.format("binaryFile").load("/Volumes/<catalog-name>/onelake-folders/files/")

Anda juga dapat mengkueri file terstruktur secara langsung:

SELECT * FROM parquet.`/Volumes/<catalog-name>/onelake-folders/files/table.parquet`

Memberikan izin pada tabel federasi

Setelah menyiapkan federasi katalog, pengguna harus memiliki izin Katalog Unity yang sesuai untuk mengakses tabel gabungan:

Semua pengguna membutuhkan izin USE CATALOG pada katalog dan izin USE SCHEMA pada skema masing-masing.
Untuk membaca dari tabel federasi, pengguna memerlukan SELECT izin.

Untuk informasi selengkapnya tentang hak istimewa Katalog Unity dan cara memberikannya, lihat Mengelola hak istimewa di Katalog Unity.

Mengkueri data OneLake

Setelah penyiapan selesai, Anda dapat menemukan dan mengkueri data OneLake di Katalog Unity.

Telusuri katalog

Di ruang kerja Databricks Anda, navigasikan ke Catalog Explorer.
Temukan katalog yang Anda buat (misalnya, fabric_sales).
Perluas katalog untuk melihat skema dan tabel yang disinkronkan dari Fabric Lakehouse atau Warehouse.

Jalankan kueri

Gunakan konvensi penamaan tiga bagian (catalog.schema.table) di Databricks SQL atau notebook:

SELECT COUNT(*)
FROM fabric_sales.silver.customer_details;

SELECT
  customer_id,
  customer_name,
  total_purchases
FROM fabric_sales.silver.customer_details
WHERE total_purchases > 1000
ORDER BY total_purchases DESC
LIMIT 10;

Keterbatasan

Federasi OneLake memiliki batasan berikut:

Akses baca-saja: Hanya SELECT kueri yang didukung. Operasi tulis tidak tersedia.
Autentikasi: Azure Managed Identity dan perwakilan layanan Azure adalah metode autentikasi yang didukung.
Item data yang didukung: Hanya item Fabric Lakehouse dan Warehouse yang didukung.
Persyaratan komputasi: Mode akses khusus tidak didukung.
Tipe data kompleks (array, peta, struct) tidak didukung.
Tampilan dan view materialisasi tidak didukung.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-29

Mengaktifkan federasi katalog OneLake

Sebelum Anda mulai

Menyiapkan federasi katalog

Langkah 1: Menyiapkan autentikasi Azure

Opsi A: Membuat konektor akses (Identitas Terkelola)

Opsi B: Mendaftarkan prinsipal layanan

Langkah 2: Memberikan izin dalam Fabric

Langkah 3: Membuat kredensial penyimpanan

Langkah 4: Membuat koneksi Katalog Unity

Eksplorer Katalog

SQL

Langkah 5: Membuat katalog asing

Memperoleh ID data item Fabric

Membuat katalog

Eksplorer Katalog

SQL

Mengakses data yang tidak terstruktur

Memberikan izin pada tabel federasi

Mengkueri data OneLake

Telusuri katalog

Jalankan kueri

Keterbatasan

Saran dan Komentar

Sumber Daya Tambahan: