從 Apache Iceberg 用戶端存取 Azure Databricks 數據表

這很重要

Unity 目錄 Apache Iceberg REST 目錄 API 在 Databricks Runtime 16.4 LTS 和更新版本中處於公開預覽狀態。此端點建議從 Iceberg 用戶端讀取與寫入資料表。

Unity Catalog 也提供 Iceberg REST 目錄的唯讀 API 端點。這是舊版端點。請參閱從 Apache Iceberg 用戶端讀取 Databricks 資料表（舊版）。

Apache Iceberg REST 目錄允許支援的客戶端，如 Apache Spark、Apache Flink 和 Trino，能從 Azure Databricks 上 Unity 目錄註冊的 Iceberg 資料表讀寫資料表。

如需支援整合的完整清單，請參閱 Unity 目錄整合。

使用 Unity Catalog 的 Iceberg 目錄端點

Unity 目錄提供 Iceberg REST 目錄 API 規格的實作。

使用端點 /api/2.1/unity-catalog/iceberg-rest設定存取。如需使用此 REST API 的詳細資訊，請參閱 Iceberg REST API 規格。

這很重要

Iceberg REST 目錄端點所用的工作區 URL 必須包含工作區 ID。若沒有工作區 ID，API 請求可能會將303導向登入頁面，而不是預期的回應。

要找到你的工作區 URL 和工作區 ID，請參見工作區實例名稱、URL 和 ID。

注意

Azure Databricks 已為某些 Iceberg 資料讀取客戶端引入認證發放功能。 Databricks 建議使用憑證管理來控制存取供支援系統使用的雲端儲存位置。如需外部系統存取，請參閱 Unity 目錄憑證發放。

如果您的用戶端不支援認證販賣，您必須設定從用戶端存取包含 Delta 或 Iceberg 資料表之檔案和元數據的儲存位置。如需設定詳細數據，請參閱 Iceberg 用戶端的檔。

要求

Azure Databricks 支援 Iceberg REST 資料庫存取表格，做為 Unity Catalog 的一部分。您必須在工作區中啟用 Unity 目錄，才能使用這些端點。以下表格類型可透過 Iceberg REST 目錄存取：

主題	參閱	書寫
管理型冰山	是的	是的
外國冰山	是的	否
受控 Delta （已啟用 Iceberg 讀取）	是的	否
外部 Delta（啟用 Iceberg 讀取功能）	是的	否

使用 Iceberg REST 目錄 API 讀取資料表時，外部 Iceberg 資料表不會自動刷新。若要重新整理，您必須執行 REFRESH FOREIGN TABLE 以讀取最新的快照。不支援外冰山數據表上的認證販賣。

注意

您必須設定 Delta 表格，才能使用 Iceberg REST 目錄 API 進行存取。請參閱使用 Iceberg 用戶端讀取 Delta 數據表。

您必須完成以下設定步驟，才能設定使用 Iceberg REST 目錄從 Iceberg 用戶端讀取或寫入 Azure Databricks 資料表的存取權限：

為中繼存放區啟用 外部數據存取。請參閱在中繼存放區上啟用外部數據存取。
給負責設定整合的主體在包含數據表的架構上授予 EXTERNAL USE SCHEMA 特權。請參閱授予主體 Unity Catalog 許可權。
使用 Azure Databricks 個人存取令牌或 OAuth 進行驗證。請參閱授權存取 Azure Databricks 資源。

注意

Iceberg 規範不允許在同一個資料表快照中重複資料檔案。為防止此情況，當偵測到時，Unity Catalog 會阻擋外部引擎將重複資料檔案提交到資料表。

搭配 Apache Spark 使用 Iceberg 數據表

以下是如何透過 Iceberg REST 目錄 API 使用 OAuth 認證來設定 Apache Spark 存取 Azure Databricks 資料表的範例：

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",

# Configuration for accessing tables in Unity Catalog
"spark.sql.catalog.<spark-catalog-name>": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.rest.auth.type": "oauth2",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg-rest",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential":"<oauth_client_id>:<oauth_client_secret>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"
"spark.sql.catalog.<spark-catalog-name>.scope":"all-apis"

取代下列變數：

<uc-catalog-name>：Unity Catalog 中包含您資料表的目錄名稱。
<spark-catalog-name>：您想要在Spark工作階段中指定給目錄的名稱。
<oauth_client_id>：驗證主體的 OAuth 用戶端識別碼。
<oauth_client_secret>：驗證主體的 OAuth 客戶端密碼。

<workspace-url>： Azure Databricks 工作空間 URL，包括工作空間 ID。例如： adb-1234567890123456.12.azuredatabricks.net 。

透過這些設定，您可以使用 Apache Spark 查詢 Unity 目錄中的數據表。若要跨多個目錄存取資料表，您必須個別設定每個目錄。

當您使用 Spark 組態查詢 Unity 目錄中的數據表時，請記住下列事項：

只有當您執行"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"時，才需要。
Azure Databricks 會針對所有數據表使用雲端物件記憶體。您必須將 iceberg-spark-runtime JAR 新增為 Spark 套件：
- AWS：org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
- Azure：org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
- GCP：org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>
如需詳細資訊，請參閱 Iceberg AWS 與 Spark 整合的文件。

注意

從 Azure Databricks 存取 Iceberg 數據表時，不需要這些設定。不支援將外部 Iceberg JAR 載入至 Azure Databricks 叢集。

使用 Snowflake 存取 Azure Databricks 資料表

Snowflake 提供兩種透過 Iceberg REST 目錄存取資料表的選項：使用 Snowflake 的目錄連結資料庫，或使用外部資料表。

對於這兩種選項，首先設定 Snowflake 目錄整合：

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest',
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

取代下列變數：

<catalog-integration-name>：您想要將註冊的目錄指派給 Snowflake 的名稱。
<uc-schema-name>：你必須存取的 Unity 目錄中結構名稱。
<uc-catalog-name>：你需要存取的 Unity Catalog 中的目錄名稱。
<workspace-url>： Azure Databricks 工作空間 URL，包括工作空間 ID。例如，https://cust-success.cloud.databricks.com/?o=6280049833385130 或 https://adb-1234567890123456.12.azuredatabricks.net。
<token>：一個個人存取權杖（PAT），用於設定整合的主體。

Snowflake 與 Entra 服務負責人 OAuth 合作

在 Azure 上，使用 Endra 支援的服務主體的 Snowflake 目錄整合無法使用 Azure Databricks OIDC 令牌端點（<workspace-url>/oidc/v1/token）。相反地，你必須直接對 Microsoft Entra 令牌端點進行認證。這與 Azure 上其他 Iceberg 用戶端（如 Apache Spark）採用的 OAuth 方法不同。

注意

Snowflake 的文件可能顯示 Entra ID 不被支援。以下設定使用 Entra OAuth 來針對 Azure Databricks 資源範圍，這是從 Snowflake 讀取 Azure 上 Unity Catalog 的支援路徑。

開始之前，請確定您擁有：

具有 EXTERNAL USE SCHEMA 權限的 Entra 服務主體被授權在 Unity 目錄中的目標結構上。請參閱授予主體 Unity Catalog 許可權。
服務負責人的客戶 ID 和客戶秘密。
您的 Azure 租用戶識別碼。

在 Snowflake 中執行以下 SQL：

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = 'https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://login.microsoftonline.com/<azure-tenant-id>/oauth2/v2.0/token'
    OAUTH_CLIENT_ID = '<entra-client-id>'
    OAUTH_CLIENT_SECRET = '<entra-client-secret>'
    OAUTH_ALLOWED_SCOPES = ('2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default')
  )
  ENABLED = TRUE
  REFRESH_INTERVAL_SECONDS = 600;

取代下列變數：

<catalog-integration-name>：您想要將註冊的目錄指派給 Snowflake 的名稱。
<uc-schema-name>：您需要存取之 Unity 目錄中的架構名稱。
<uc-catalog-name>：您需要存取的 Unity 目錄中目錄名稱。
<workspace-url>： Azure Databricks 工作空間 URL，包括工作空間 ID。例如： adb-1234567890123456.12.azuredatabricks.net 。
<azure-tenant-id>：Microsoft Entra 租戶 ID。
<entra-client-id>： Entra 服務主體的應用程式（用戶端）ID。
<entra-client-secret>：Entra 服務主體的用戶端密碼。

這很重要

範圍 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default 是已在 Entra 註冊的 Azure Databricks 應用程式 ID。這與 Azure Databricks OIDC 端點所使用的範圍不同 all-apis 。使用錯誤的範圍是設定此整合時認證失敗的常見原因。

建立目錄整合後，依照 Snowflake 文件建立一個目錄連結的資料庫以存取資料表。

欲了解更多關於為 Azure Databricks 建立及管理 Entra 服務主體的資訊，請參閱「使用 Microsoft Entra 服務主體認證」。

注意

Snowflake 不支援使用 Entra 認證，用於使用私有網路（Azure Private Link）連接 Azure Databricks 的目錄整合。與 Azure Databricks Iceberg REST 目錄端點的連線，在使用 Entra 服務主體認證時必須使用公開網路。

目錄連結資料庫

Snowflake 的目錄連結資料庫會自動與 Unity 目錄同步，以偵測結構與 Iceberg 表格。這消除了手動更新元資料的需求。

設定 Snowflake 目錄整合後，請參考 Snowflake 文件建立目錄連結資料庫以存取您的資料表。

這很重要

嘗試從 Snowflake 寫入唯讀的 Azure Databricks 資料表可能會導致錯誤。請參閱 Snowflake 文件以了解支援的操作。

外部數據表

或者，你也可以在建立 Snowflake 目錄整合後建立外部資料表。此方法需手動刷新元資料以查看更新。

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = '<catalog-integration-name>'
  CATALOG_TABLE_NAME = '<uc-table-name>';

搭配 PyIceberg 使用 Azure Databricks 數據表

要使用 PyIceberg 存取 Azure Databricks 資料表，必須安裝具備所需相依關係的 PyIceberg。 PyIceberg 需要 pyarrow 進行資料表操作，例如讀取資料和檢查資料表元資料。安裝帶有pyarrow附加元件的 PyIceberg：

pip install "pyiceberg[pyarrow]"

注意

若未安裝 pyarrow，描述或讀取資料表等操作將失敗。欲了解完整的可選相依性清單，請參閱 PyIceberg 文件。

以下是組態設定的範例，可讓 PyIceberg 連線到 Unity 目錄中的 Iceberg REST 目錄，以存取 Azure Databricks 數據表：

catalog:
  unity_catalog:
    uri: https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest
    warehouse: <uc-catalog-name>
    token: <token>

取代下列變數：

<workspace-url>： Azure Databricks 工作空間 URL，包括工作空間 ID。例如： adb-1234567890123456.12.azuredatabricks.net 。

<uc-catalog-name>：你需要存取的 Unity 目錄名稱。
<token>：用於配置整合的主體的個人存取權杖（PAT）。

請參閱 PyIceberg REST 目錄設定的檔。

REST API curl 範例

以下 curl 範例使用 REST API 載入一個資料表：

curl -X GET -H "Authorization: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg-rest/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

回應看起來像這樣：

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

注意

欄位顯示 expires-at-ms 資格過期時間。預設的有效期限是一小時。為了提升效能，讓客戶端先快取憑證直到過期後再申請新的憑證。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-03-21

共用方式為

從 Apache Iceberg 用戶端存取 Azure Databricks 數據表

使用 Unity Catalog 的 Iceberg 目錄端點

要求

搭配 Apache Spark 使用 Iceberg 數據表

使用 Snowflake 存取 Azure Databricks 資料表

Snowflake 與 Entra 服務負責人 OAuth 合作

目錄連結資料庫

外部數據表

搭配 PyIceberg 使用 Azure Databricks 數據表

REST API curl 範例

意見反應

其他資源