本文說明如何利用目錄聯盟在 OneLake 中讀取資料。 這使得 Unity 目錄查詢能直接對 OneLake 儲存執行。
OneLake 同盟讓你能分析儲存在 Lakehouse 或 Warehouse 中的資料而不複製,將 Azure Databricks 中的分析與 AI/BI 功能直接帶到 OneLake 資料中。 資料存取為唯讀。
Requirements
您必須符合以下條件,才能在 OneLake 上使用目錄聯盟執行聯邦查詢:
工作區需求:
- 已為 Unity Catalog 啟用了工作區。
計算需求:
- 從你的運算資源到OneLake的網路連線。 如果 Fabric 工作區阻擋了公共網路存取,請參見「連接阻擋公共存取的 Fabric 工作區」。 如需一般指引,請參閱 Lakehouse Federation 的網路建議。
- Azure Databricks 的運算必須使用 Databricks Runtime 18.0 或以上版本及標準存取模式。
- SQL 倉庫必須使用 2025.40 或更高版本。
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 進行認證。
在 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。
- 在 「憑證與秘密」中,建立一個新的客戶端秘密並記錄秘密 值。
如果 Fabric 工作空間位於不同的 Microsoft Entra 租戶中,該應用程式必須在該租戶中擁有服務主體。 請參閱「連接至另一個租戶中的 Fabric 工作區」。
步驟 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來建立記憶體認證。
如果 Fabric 工作空間位於不同的 Microsoft Entra 租戶中,請設定directory_id為該 Fabric 租戶的目錄 ID。 請參閱「連接至另一個租戶中的 Fabric 工作區」。
步驟 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 表格立即可用。
連接到另一個租戶中的 Fabric 工作區
你建立同盟的 Fabric 工作空間可以位於與 Azure Databricks 工作空間不同的 Microsoft Entra 租戶中。 跨租戶存取需要包含 Fabric 工作空間的租戶中有一個服務主體,因為受管理身份無法向其他租戶進行認證。
完成設定目錄聯盟中的步驟,並進行以下變更:
- 在步驟 1 中,使用一個在 Fabric 租戶中有服務主體的 Microsoft Entra 應用程式。 該應用程式可以是註冊於 Fabric 租戶中的單一租戶應用程式,或是由 Fabric 租戶中 Microsoft Entra ID 管理員同意的多租戶應用程式。 請參閱 Microsoft Entra ID 中的應用程式與服務主體物件。
- 在步驟 2 中,Fabric 工作區管理員授予該服務主體對工作區或個別資料項目的存取權。 Fabric 租戶的管理員也必須啟用 Requirements 中列出的 Fabric 租戶與工作空間設定。 該應用程式不需要 Microsoft Entra ID 的任何 API 權限。
- 在第三步,將
directory_id設定為 Fabric 租用戶的目錄(租用戶)ID,而不是您自己的租用戶 ID。 Unity Catalog 使用服務主體向包含 Fabric 工作空間的租戶請求權杖。
如果 Fabric 工作區封鎖了公用網際網路存取,請先設定私用端點,再於步驟 4 建立連線。 請參閱另一個租戶中 Fabric 工作空間的私有端點。
連接到阻擋公開存取的 Fabric 工作區
Fabric 工作區可以阻擋 OneLake 的公共網路存取。 你如何連接它,取決於 Fabric 工作空間是否與你的 Azure Databricks 工作空間在同一個 Microsoft Entra 租戶中:
- 同一租戶:在 Fabric 工作區中使用資源實例規則將你的存取連接器加入允許清單。 請參考同一租戶中的 Fabric 工作區。
- 另一個租戶:透過私有端點連接到 Fabric 工作區的 Private Link 服務。 請參閱另一個租戶中 Fabric 工作空間的私有端點。
位於同一租用戶中的 Fabric 工作區
當 Fabric 工作區與你的 Azure Databricks 工作區在同一租戶時,使用管理身份驗證,並透過 Fabric 工作區上的資源實例規則允許存取連接器。 資源實例規則不會跨租戶套用。
- 在 建立目錄聯盟時,使用步驟 1 的選項 A 建立存取連接器,並記錄其資源 ID。 其格式為
/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Databricks/accessConnectors/<connector-name>。 - 請 Fabric 工作區管理員將存取連接器的資源 ID 新增為資源執行個體規則。 在 Fabric 工作區中,管理員選擇工作區設定>入站網路,限制對特定網路及核准資源的存取,並新增資源 ID。 Fabric 管理員必須先啟用允許工作區層級入站網路保護的租戶設定。 請參閱 Microsoft Fabric 文件中的「以資源實例規則管理 OneLake 的入站存取」。
- 完成 設定目錄聯盟 中的其餘步驟。
另一個租戶中 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。
- 建立網路連接設定(NCC),並將其附加到你的工作區。 請參見 建立網路連線設定 和 將 NCC 附加至工作區。
- 在 NCC 中加入私人端點規則。 對於 Azure 資源 ID,請輸入 Private Link 服務資源 ID。 對於 Azure 子資源類型,請輸入
workspace. 請參見 建立私有端點規則。 - 請 Fabric 租戶中的管理員批准待處理的私有端點連線。
- 重新整理 NCC 頁面直到規則狀態為
ESTABLISHED,然後重新啟動任何正在執行的無伺服器運算。 請參閱重新啟動無伺服器運算平面資源並測試連線。
傳統運算資源
經典運算需要在你自己的虛擬網路中部署一個工作空間。 請參閱<在 Azure 虛擬網路 (VNet 插入) 中部署 Azure Databricks>。
以下步驟改寫自 Microsoft Fabric 文件中使用工作空間層級私有連結的跨租用戶連線的步驟 5 到 7。 使用工作區的虛擬網路,而不是建立新的虛擬網路和虛擬機器。
- 在 Azure 入口網站中,在工作區虛擬網路的子網路中建立一個私人端點。 選擇以資源 ID 或別名連接 Azure 資源,輸入 Private Link 服務資源 ID,並選擇 workspace 作為目標子資源。
Microsoft.Fabric資源提供者必須在你建立私有端點的 Azure 訂閱中註冊。 - 請 Fabric 租戶中的管理員批准待處理的私有端點連線。
- 建立一個命名為
privatelink.fabric.microsoft.com私人 DNS 區域,並將其連結到工作空間的虛擬網路。 確保私有端點 DNS 設定 頁面上列出的每筆紀錄都包含在這個 DNS 區域中,包括 OneLake 端點,例如<workspace-id>.z<xy>.dfs.fabric.microsoft.com。 在這些名稱中,<workspace-id>是 Fabric 工作區 ID(不含破折號),<xy>是其前兩個字元。 - 如果網路安全群組規則限制了來自工作區子網的出站流量,請允許 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 資料。
瀏覽目錄
- 在你的 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;
同步表格與欄註解
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 檔案。 請參見 存取非結構化資料。