啟用 OneLake 目錄聯盟

本文說明如何利用目錄聯盟在 OneLake 中讀取資料。這使得 Unity 目錄查詢能直接對 OneLake 儲存執行。

OneLake 聯邦讓你能在不複製的情況下分析儲存在 Lakehouse 或 Warehouse 的資料，將 Azure Databricks 強大的分析及 AI/BI 功能直接整合到 OneLake 資料中。資料存取為唯讀。

開始之前

您必須符合以下條件，才能在 OneLake 上使用目錄聯盟執行聯邦查詢：

工作區需求：

已為 Unity Catalog 啟用了工作區。

計算需求：

您的計算資源與目標資料庫系統之間的網路連接能力。請參閱 Lakehouse Federation 的網路建議。
Azure Databricks 的運算必須使用 Databricks Runtime 18.0 或以上版本及標準存取模式。
SQL 倉庫必須使用 2025.40 或更高版本。

需要的權限：

要建立連線，你必須是 metastore 管理員，或是擁有「Unity Catalog metastore」附加到工作區上的 CREATE CONNECTIONCREATE STORAGE CREDENTIAL 權限的使用者。
若要建立外來目錄，您必須具有中繼存放區的 CREATE CATALOG 許可權，並且必須是連線的擁有者或具有該連線的 CREATE FOREIGN CATALOG 特權。

在後續每個以任務為基礎的章節中，會指定額外的權限要求。

你必須擁有在 Azure 建立資源、在 Fabric 中設定存取權限，以及在 Azure Databricks 管理 Unity 目錄的權限。
支援的認證方法：
- Azure 託管身分經由 Azure Databricks 的存取連接器
- Azure 服務主體

Fabric 租戶與工作區設定：

Fabric 管理員必須啟用服務主體可呼叫 Fabric 公共 API 租戶設定。這讓受管理身份與服務主體能夠與 Fabric 進行認證。欲了解更多資訊，請參閱服務主要租戶設定。
Fabric 管理員必須啟用允許在 Fabric 外部執行的應用程式透過 OneLake 存取資料的租戶設定。這讓 Azure Databricks 能夠連接到 OneLake 儲存裝置。更多資訊請參閱「允許在 Fabric 外執行的應用程式透過 OneLake 存取資料」。
Fabric 管理員必須啟用 使用短期用戶委派的 SAS 權杖 租戶設定。此設定允許 OneLake 發行由 Entra 支援的短命 SAS 令牌，Azure Databricks 用於讀取 OneLake 資料。欲了解更多資訊，請參閱 OneLake 共享存取簽章。
在包含你資料的 Fabric 工作區中，必須啟用 OneLake 使用者委派的 SAS 憑證 驗證。進入工作區設定>委派設定>OneLake 設定以啟用此設定。

以下支援的 Fabric 資料項目：

Fabric湖倉
布料倉庫

設定目錄同盟

以下步驟將引導您建立 OneLake 聯盟的連結與海外目錄。

步驟 1：設定 Azure 認證

OneLake 聯盟支援兩種認證方式。

Azure 管理身份（建議）：使用 Databricks 存取連接器搭配管理身份。
Azure Service Principal：使用 Microsoft Entra ID 應用程式並使用客戶端憑證。此方法支援跨租戶認證，讓 Databricks 能存取位於不同 Azure 租戶中的 Fabric 工作空間。

選項 A：建立存取連接器（管理身份）

Databricks Access Connector 建立一個管理身份，Azure Databricks 用來與 OneLake 進行認證。

在 Azure 入口網站中，搜尋並建立一個新的 Access Connector for Azure Databricks 資源。
依照提示製作連接器。此資源建立系統指派的管理身份（Managed Identity）。
記錄新建立連接器的 資源 ID 。建立 Unity Catalog 儲存憑證時，你需要這個 ID。

資源識別碼的格式如下：
```
/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Databricks/accessConnectors/<connector-name>
```

欲了解更多關於建立存取連接器及使用受管理身份的資訊，請參閱「在 Unity 目錄中使用 Azure 管理身份以存取儲存裝置」。

選項B：註冊服務主體

如果你偏好使用服務主體而非受管理身份：

在 Azure 入口網站，導覽到 Microsoft Entra ID>應用程式註冊， 註冊一個新應用程式（或使用現有的）。
記錄 應用程式（用戶端）ID 與 目錄（租戶）ID。
在 「憑證與秘密」中，建立一個新的客戶端秘密並記錄秘密值。

步驟 2：在 Fabric 中授予權限

授予受管理身份或服務主體讀取 Fabric 資料的權限。你可以授權一個工作區角色，涵蓋工作區中的所有資料項目，或只授予你想要聯合的資料項目權限。

選項 A：指派工作區角色

在 Fabric 入口網站中，導覽到包含 Lakehouse 或 Warehouse 資料項目的工作區。
在工作區中，點選 工作區設定 的齒輪圖示，然後點 選管理存取。
點選 新增人員或群組。
搜尋並選擇受管理的身分識別或服務主體名稱。對於管理身份，名稱應該會和你之前建立的存取連接器相符。對於服務主體，請搜尋你註冊的應用程式名稱。
至少將身份分配為貢獻者角色。您也可以指派成員或 管理員 角色。
按下新增。
確認該身份是否以適當角色出現在存取清單中。 Lakehouse 和 Warehouse 個別項目的權限是從工作區層級角色繼承而來。

選項 B：對個別資料項目授予權限

Azure Databricks 會透過 OneLake API 讀取 OneLake 資料，因此身份需要一個權限才能讓 OneLake 有讀取權限。僅限 SQL 的權限（透過 SQL 分析端點讀取所有資料）並不足夠。

在你對個別資料項目分配權限之前，先在 Fabric 工作區層級將身份指定為檢視者角色。請依照選項 A 的步驟操作，選擇 「檢視者 」而非「 貢獻者」。

在 Fabric 入口網站中，導覽到包含你資料項目的工作區。
在你想聯合的資料項目旁邊，點選省略號（...），然後點選 管理權限。
點選 新增使用者，然後搜尋並選擇管理身份或服務主體。
選擇賦予 OneLake 讀取權限的 「全部閱讀」 權限。根據項目類型和你的 Fabric 版本，這個權限會標示為「Read all with Apache Spark」或「Read all OneLake data」。更多資訊請參閱 Microsoft Fabric 文件中的項目權限。
請按一下授權。
對每個你想聯邦化的資料項目重複這些步驟。

步驟 3：建立儲存憑證

在 Unity Catalog 建立一個儲存憑證，參考你在步驟 1 中設定的身份。

在您的 Azure Databricks 工作區中，按一下目錄。
在目錄窗格頂端，點選「新增或加號」圖示，從選單中選擇 「建立憑證」。

如果你使用的是受管身份：

在 「建立新憑證 」模式中，對於 憑證類型，選擇 Azure 管理身份。
對於 憑證名稱，請輸入儲存憑證的名稱（例如， onelake_storage_cred。
對於 存取連接器 ID，請輸入你先前建立的存取連接器的資源 ID。
(選擇性) 新增註解。
點擊建立。

如果您正在使用服務負責人：

你無法使用 Catalog Explorer 建立服務主體儲存憑證。你必須是 Azure Databricks 帳號管理員，並且使用 Storage Credentials API。例如：

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"
   }'

您也可以使用 Databricks Terraform 提供者和 databricks_storage_credential來建立記憶體認證。

步驟 4：建立 Unity 目錄連結

建立一個 Unity 目錄連線，使用儲存憑證來存取 OneLake。

目錄檢視器

在您的 Azure Databricks 工作區中，按一下目錄。
在目錄面板頂端，點選加號圖示，從選單中選擇 建立連線 。
在 連線基礎 頁面輸入 連線名稱 （例如， onelake_connection）。
選擇 OneLake 的連線類型。
(選擇性) 新增註解。
按 [下一步]。
在連線詳情頁面的憑證選項中，選擇你在前一步建立的儲存憑證（例如）。 onelake_storage_cred
在工作區中，請輸入你的 Fabric 工作區 ID。
點選 「建立連線」。

SQL

在筆記本或 Databricks SQL 查詢編輯器中，執行下列命令。替換占位符值：

<connection-name>：這個連結的名稱。
<workspace-id>: 你的 OneLake 工作空間的 GUID。
<storage-credential-name>：你在步驟3中建立的儲存憑證名稱。

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

步驟五：建立外國目錄

外部目錄將特定的 Fabric 資料項目連結到 Unity 目錄中的目錄。

取得 Fabric 資料項 ID

在 Fabric 門戶中，導航至目標的 Lakehouse 或倉庫。
複製 資料項目 ID，這是一個 GUID（例如， f089354e-8366-4e18-aea3-4cb4a3a50b48）。

你可以在 Fabric UI 中找到這個 GUID，或在你瀏覽到 Lakehouse 或 Warehouse 時，從瀏覽器的 URL 複製它：
```
https://app.fabric.microsoft.com/groups/<workspace-id>/lakehouses/<data-item-id>?experience=power-bi
```

建立目錄

目錄檢視器

在你的 Databricks 工作區，點選目錄。
在目錄面板頂端，點選加號圖示，從選單中選擇 建立目錄 。
在 「建立新目錄 」對話框中，輸入目錄名稱（例如， fabric_sales）。
選擇一種外國產品。
選擇你在步驟 4 建立的連線（例如， onelake_connection）。
對於 資料項目，輸入您從 Fabric 門戶複製的資料項目 ID。
在 項目類型中，從下拉選單中選擇與你的資料項目相符的類型。
（可選）點擊 測試連線 以驗證你的設定。
點擊建立。

SQL

請在筆記本或 Databricks SQL 查詢編輯器中執行以下 SQL 指令。方括號內的項目為可選。替換占位符值：

<catalog-name>：Azure Databricks 中目錄的名稱。
<connection-name>：你在第四步建立的連結。
<data-item-id>：布料湖屋或倉庫的指導者。
<item-type>： Lakehouse 或 Warehouse。

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

您也可以指定以下可選參數：

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

create_volume_for_lakehouse_files： true （預設值）或 false。當 true時，為 Lakehouse 的資料夾建立一個體積 /Files 。僅適用於 Lakehouse 的項目。請參見存取非結構化資料。

目錄會自動同步，讓 Fabric 表格立即可用。

存取非結構化資料

OneLake 聯盟支援只讀存取儲存在 Lakehouse 資料夾中的 /Files 非結構化資料。這是透過 Unity 目錄儲存量來實現的。

當你建立一個外部目錄並將create_volume_for_lakehouse_files設定為true預設值時，會在onelake-folders結構下自動建立一個卷。此卷將指向 Lakehouse 的/Files資料夾，並提供對儲存在該處檔案的只讀存取權限。

你可以透過磁碟區路徑瀏覽和讀取檔案：

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

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

你也可以直接查詢結構化檔案：

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

授予聯邦資料表權限

設定目錄聯盟後，使用者必須擁有適當的 Unity 目錄權限才能存取聯邦資料表：

所有使用者需要目錄的 USE CATALOG 權限和結構的 USE SCHEMA 權限。
使用者若要從聯邦表格讀取，需取得 SELECT 權限。

欲了解更多關於 Unity 目錄權限及授予方式，請參閱管理 Unity 目錄中的權限。

查詢 OneLake 資料

設定完成後，你可以在 Unity 目錄中查找並查詢 OneLake 資料。

瀏覽目錄

在你的 Databricks 工作區中，進入 目錄總管。
找到你所建立的目錄（例如， fabric_sales）。
展開目錄以查看來自 Fabric Lakehouse 或 Warehouse 的同步結構與資料表。

執行查詢

在 Databricks SQL 或筆記本中，使用三部分命名慣例（catalog.schema.table）：

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;

局限性

OneLake 聯盟有以下限制：

唯讀存取：僅支援 SELECT 查詢。無法進行寫入操作。
認證：Azure 管理身份（Managed Identity）和 Azure 服務主體是支援的認證方法。
支援的資料項目：僅支援 Fabric Lakehouse 與 Warehouse 項目。
運算需求：不支援專用存取模式。
不支援複雜的資料型別（陣列、映射、結構）。
具體化觀點與觀點不被支持。
建立連線後，你無法更新連線選項（例如 workspace）。
欄位名稱僅大小寫不同的資料表（例如，id 和 ID）不受支援。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-24

啟用 OneLake 目錄聯盟

開始之前

設定目錄同盟

步驟 1：設定 Azure 認證

選項 A：建立存取連接器（管理身份）

選項B：註冊服務主體

步驟 2：在 Fabric 中授予權限

選項 A：指派工作區角色

選項 B：對個別資料項目授予權限

步驟 3：建立儲存憑證

步驟 4：建立 Unity 目錄連結

目錄檢視器

SQL

步驟五：建立外國目錄

取得 Fabric 資料項 ID

建立目錄

目錄檢視器

SQL

存取非結構化資料

授予聯邦資料表權限

查詢 OneLake 資料

瀏覽目錄

執行查詢

局限性

意見反應

其他資源