啟用 OneLake 目錄聯盟

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

OneLake 同盟讓你能分析儲存在 Lakehouse 或 Warehouse 中的資料而不複製,將 Azure Databricks 中的分析與 AI/BI 功能直接帶到 OneLake 資料中。 資料存取為唯讀。

Requirements

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

工作區需求:

  • 已為 Unity Catalog 啟用了工作區。

計算需求:

Note

在 Databricks Runtime 19 及以上版本中,Azure Databricks 的運算會透過每個 Fabric 工作空間的獨立端點(例如 <workspace-id>.z<xy>.dfs.fabric.microsoft.com,)讀取 OneLake 資料,而非全域onelake.dfs.fabric.microsoft.com端點。 如果你為全域端點設定了自訂 DNS 紀錄或外出防火牆規則,務必確保它們也涵蓋工作區端點。 請參閱 Microsoft Fabric 文件中的更多 OneLake 端點。

小提示

為了降低延遲並避免跨區域資料傳輸費用,請在與承載您資料的 Fabric 容量相同的 Azure 區域內使用 Azure Databricks 工作區。

需要的權限:

  • 要建立連線,你必須是 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 工作空間與你的 Azure Databricks 工作區位於同一個 Microsoft Entra 租戶中,Fabric 工作區管理員必須將 Azure Databricks Access Connector 的資源 ID 加入工作區的資源實例規則中。 如果它位於另一個租戶中,你就透過私有端點連接。 請參閱「連接至阻擋公共存取的 Fabric 工作區」。

以下支援的 Fabric 資料項目:

  • Fabric湖倉
  • 布料倉庫

設定目錄同盟

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

步驟 1:設定 Azure 認證

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

  • Azure Managed Identity(推薦):使用 Access Connector for Azure Databricks,並使用受控識別。
  • Azure Service Principal:使用 Microsoft Entra ID 應用程式並使用客戶端憑證。 此方法支援跨租戶認證,讓 Azure Databricks 能存取位於不同 Azure 租戶中的 Fabric 工作空間。 請參閱「連接至另一個租戶中的 Fabric 工作區」。

選項 A:建立存取連接器(管理身份)

Azure Databricks 的存取連接器會建立一個受控識別,Azure Databricks 用來與 OneLake 進行認證。

  1. 在 Azure 入口網站 中,搜尋並建立一個新的 Access Connector for Azure Databricks 資源。

  2. 依照提示製作連接器。 此資源建立系統指派的管理身份(Managed Identity)。

  3. 記錄新建立連接器的 資源 ID 。 建立 Unity Catalog 儲存憑證時,你需要這個 ID。

    資源識別碼的格式如下:

    /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Databricks/accessConnectors/<connector-name>
    

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

選項B:註冊服務主體

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

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

如果 Fabric 工作空間位於不同的 Microsoft Entra 租戶中,該應用程式必須在該租戶中擁有服務主體。 請參閱「連接至另一個租戶中的 Fabric 工作區」。

步驟 2:在 Fabric 中授予權限

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

選項 A:指派工作區角色

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

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

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

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

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

步驟 3:建立儲存憑證

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

  1. 在您的 Azure Databricks 工作區中,按一下 [資料] 圖示。目錄。
  2. 在 目錄 窗格頂端,點選 Add or plus icon「新增或加號」圖示,從選單中選擇 「建立憑證」。

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

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

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

你無法使用 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來建立記憶體認證。

如果 Fabric 工作空間位於不同的 Microsoft Entra 租戶中,請設定directory_id為該 Fabric 租戶的目錄 ID。 請參閱「連接至另一個租戶中的 Fabric 工作區」。

步驟 4:建立 Unity 目錄連結

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

目錄檢視器

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

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

  1. 在 Fabric 門戶中,導航至目標的 Lakehouse 或倉庫。

  2. 複製 資料項目 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
    

建立目錄

目錄檢視器
  1. 在你的 Databricks 工作區,點選 Data 圖示。目錄。
  2. 在 目錄 面板頂端,點選 新增或加號圖示 加號圖示,從選單中選擇 建立目錄 。
  3. 在 「建立新目錄 」對話框中,輸入目錄名稱(例如, fabric_sales)。
  4. 選擇一種外國產品。
  5. 選擇你在步驟 4 建立的 連線 (例如, onelake_connection)。
  6. 對於 資料項目,輸入您從 Fabric 門戶複製的資料項目 ID。
  7. 在 項目類型中,從下拉選單中選擇與你的資料項目相符的類型。
  8. (可選)點擊 測試連線 以驗證你的設定。
  9. 點擊 建立。
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 表格立即可用。

連接到另一個租戶中的 Fabric 工作區

你建立同盟的 Fabric 工作空間可以位於與 Azure Databricks 工作空間不同的 Microsoft Entra 租戶中。 跨租戶存取需要包含 Fabric 工作空間的租戶中有一個服務主體,因為受管理身份無法向其他租戶進行認證。

完成設定目錄聯盟中的步驟,並進行以下變更:

  1. 在步驟 1 中,使用一個在 Fabric 租戶中有服務主體的 Microsoft Entra 應用程式。 該應用程式可以是註冊於 Fabric 租戶中的單一租戶應用程式,或是由 Fabric 租戶中 Microsoft Entra ID 管理員同意的多租戶應用程式。 請參閱 Microsoft Entra ID 中的應用程式與服務主體物件。
  2. 在步驟 2 中,Fabric 工作區管理員授予該服務主體對工作區或個別資料項目的存取權。 Fabric 租戶的管理員也必須啟用 Requirements 中列出的 Fabric 租戶與工作空間設定。 該應用程式不需要 Microsoft Entra ID 的任何 API 權限。
  3. 在第三步,將 directory_id 設定為 Fabric 租用戶的目錄(租用戶)ID,而不是您自己的租用戶 ID。 Unity Catalog 使用服務主體向包含 Fabric 工作空間的租戶請求權杖。

如果 Fabric 工作區封鎖了公用網際網路存取,請先設定私用端點,再於步驟 4 建立連線。 請參閱另一個租戶中 Fabric 工作空間的私有端點。

連接到阻擋公開存取的 Fabric 工作區

Fabric 工作區可以阻擋 OneLake 的公共網路存取。 你如何連接它,取決於 Fabric 工作空間是否與你的 Azure Databricks 工作空間在同一個 Microsoft Entra 租戶中:

位於同一租用戶中的 Fabric 工作區

當 Fabric 工作區與你的 Azure Databricks 工作區在同一租戶時,使用管理身份驗證,並透過 Fabric 工作區上的資源實例規則允許存取連接器。 資源實例規則不會跨租戶套用。

  1. 在 建立目錄聯盟時,使用步驟 1 的選項 A 建立存取連接器,並記錄其資源 ID。 其格式為 /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Databricks/accessConnectors/<connector-name>。
  2. 請 Fabric 工作區管理員將存取連接器的資源 ID 新增為資源執行個體規則。 在 Fabric 工作區中,管理員選擇工作區設定>入站網路,限制對特定網路及核准資源的存取,並新增資源 ID。 Fabric 管理員必須先啟用允許工作區層級入站網路保護的租戶設定。 請參閱 Microsoft Fabric 文件中的「以資源實例規則管理 OneLake 的入站存取」。
  3. 完成 設定目錄聯盟 中的其餘步驟。

另一個租戶中 Fabric 工作空間的私有端點

當 Fabric 工作區位於另一個租用戶時,Azure Databricks 計算會使用工作區層級的 private link,透過連接到工作區 Private Link 服務的私人端點連線到 OneLake。 請參閱 Microsoft Fabric 文件中的使用工作區層級私人連結的跨租用戶連線。 Fabric 租戶的管理員建立 Private Link 服務,然後你如以下各節所述,建立私有端點。

要求:

  • 經典運算資源必須使用 Databricks Runtime 19 或以上。
  • 你需要 Fabric 工作區的 Private Link 服務的資源 ID,這由 Fabric 工作區管理員提供給你。 其格式為 /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Fabric/privateLinkServicesForFabric/<name>。

每個 Fabric 工作區都有自己的 Private Link 服務,所以你為每個聯邦化的 Fabric 工作區建立一個私人端點。 在 設定目錄聯盟 中建立連線和外部目錄之前,請先建立私有端點。

透過私有端點,OneLake 聯邦支援 Lakehouse 和 Warehouse 項目中的資料表。 不支援存取 Lakehouse 檔案。 請參見 存取非結構化資料。

無伺服器運算

Databricks 建議這種配置使用無伺服器運算,因為 Azure Databricks 會幫你建立私有端點並管理其 DNS。

  1. 建立網路連接設定(NCC),並將其附加到你的工作區。 請參見 建立網路連線設定 和 將 NCC 附加至工作區。
  2. 在 NCC 中加入私人端點規則。 對於 Azure 資源 ID,請輸入 Private Link 服務資源 ID。 對於 Azure 子資源類型,請輸入 workspace. 請參見 建立私有端點規則。
  3. 請 Fabric 租戶中的管理員批准待處理的私有端點連線。
  4. 重新整理 NCC 頁面直到規則狀態為 ESTABLISHED,然後重新啟動任何正在執行的無伺服器運算。 請參閱重新啟動無伺服器運算平面資源並測試連線。

傳統運算資源

經典運算需要在你自己的虛擬網路中部署一個工作空間。 請參閱<在 Azure 虛擬網路 (VNet 插入) 中部署 Azure Databricks>。

以下步驟改寫自 Microsoft Fabric 文件中使用工作空間層級私有連結的跨租用戶連線的步驟 5 到 7。 使用工作區的虛擬網路,而不是建立新的虛擬網路和虛擬機器。

  1. 在 Azure 入口網站中,在工作區虛擬網路的子網路中建立一個私人端點。 選擇以資源 ID 或別名連接 Azure 資源,輸入 Private Link 服務資源 ID,並選擇 workspace 作為目標子資源。 Microsoft.Fabric資源提供者必須在你建立私有端點的 Azure 訂閱中註冊。
  2. 請 Fabric 租戶中的管理員批准待處理的私有端點連線。
  3. 建立一個命名為 privatelink.fabric.microsoft.com 私人 DNS 區域,並將其連結到工作空間的虛擬網路。 確保私有端點 DNS 設定 頁面上列出的每筆紀錄都包含在這個 DNS 區域中,包括 OneLake 端點,例如<workspace-id>.z<xy>.dfs.fabric.microsoft.com。 在這些名稱中,<workspace-id> 是 Fabric 工作區 ID(不含破折號),<xy> 是其前兩個字元。
  4. 如果網路安全群組規則限制了來自工作區子網的出站流量,請允許 443 埠連接到私有端點。

驗證私有連線

建立外部目錄後,查詢裡面的表格。 查詢成功後,確認流量確實使用了私有端點。

你也可以測試連線,並在目錄瀏覽器中瀏覽外部目錄的結構與資料表。

存取非結構化資料

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

Note

不支援存取你透過私人端點連線到另一個租用戶之 Fabric 工作區中的 Lakehouse 檔案。 請參閱另一個租戶中 Fabric 工作空間的私有端點。 當你為這些工作區建立外部目錄時,可以將 create_volume_for_lakehouse_files 設為 false,以跳過建立該磁碟區。

當你建立一個外部目錄並將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 資料。

瀏覽目錄

  1. 在你的 Databricks 工作區中,進入 目錄總管。
  2. 找到你所建立的目錄(例如, fabric_sales)。
  3. 展開目錄以查看來自 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;

同步表格與欄註解

Azure Databricks 支援從外部資料來源同步表格與欄位註解。 註解同步需要 Databricks 執行時 18 LTS 或以上,或是執行 Databricks SQL 2026.15 或以上版本的 SQL 倉庫。 請參考 SQL 倉庫通道。

Azure Databricks 在解析外部表元資料時會取得註解。 同步的註解會出現在目錄總管中,以及在 DESCRIBE 和 DESCRIBE EXTENDED 輸出中。 當外部來源的註解有變動時,Azure Databricks 會在下一次解析外部資料表中繼資料時同步這些變更。 若要在不查詢資料表資料的情況下刷新註解,請執行:

DESCRIBE EXTENDED <catalog-name>.<schema-name>.<table-name>;

Lakeflow 管線在解析外部資料表元資料時,不會從外部來源擷取註解。

局限性

OneLake 聯盟有以下限制:

  • 唯讀存取:僅支援 SELECT 查詢。 無法進行寫入操作。
  • 認證:Azure 管理身份(Managed Identity)和 Azure 服務主體是支援的認證方法。
  • 支援的資料項目:僅支援 Fabric Lakehouse 與 Warehouse 項目。
  • 運算需求:不支援專用存取模式。
  • 不支援複雜的資料型別(陣列、映射、結構)。
  • 具體化觀點與觀點不被支持。
  • 建立連線後,你無法更新連線選項(例如 workspace)。
  • 欄位名稱僅大小寫不同的資料表(例如,id 和 ID)不受支援。
  • 透過私有端點連線至另一個租戶中的 Fabric 工作空間時,不支援 Lakehouse 檔案。 請參見 存取非結構化資料。