從 Delta 用戶端存取 Databricks 資料表

本頁說明如何使用 Unity REST API 從外部 Delta 用戶端建立、讀取及寫入 Unity 目錄管理及外部資料表。 如需支援整合的完整清單，請參閱 Unity 目錄整合。

Tip

關於如何使用 Microsoft Fabric 來讀取已在 Unity Catalog 中註冊的 Azure Databricks 資料的資訊，請參見 使用 Microsoft Fabric 讀取已在 Unity Catalog 中註冊的資料。

使用 Unity REST API 來建立、讀取和寫入

這很重要

從 Delta 客戶端建立並寫入 Unity Catalog 管理的資料表目前仍處於測試階段。 外部客戶支援有限。

Unity REST API 提供外部用戶端對註冊於 Unity 目錄的資料表建立、讀取及寫入權限。 以 工作區 URL 作為端點來設定存取權限。 以下表格類型可供存取：

數據表類型 參閱 書寫 Create
管理達美 是的 是* 是*
外部三角洲 是的 是的 是的

* 支援具有 目錄提交功能的管理型 Delta 資料表。

要求

Azure Databricks 支援 Unity REST API 存取資料表，作為 Unity 目錄的一部分。 您必須在工作區中啟用 Unity 目錄，才能使用這些端點。

你也必須完成以下設定步驟，以設定使用 Unity REST API 從 Delta 用戶端存取資料表：

局限性

  • 目前不支援使用 IcebergCompatV3 外部存取 UniForm 資料表。 外部寫入 UniForm 資料表後，必須在 Databricks 執行 MSCK REPAIR TABLE 以產生 Iceberg 元資料。
  • 目前外部客戶端的管理資料表不支援結構變更（例如）、 ALTER TABLE資料表屬性更新及資料表功能變更。
  • 外部用戶端無法對受管理的 Delta 資料表執行資料表維護操作，例如 OPTIMIZE、 VACUUM、 ANALYZE和 。
  • 外部客戶端無法建立 淺層複製品。
  • 外部用戶端無法建立包含產生欄位、預設欄位或限制欄位的資料表。
  • 在建立外部資料表時，Azure Databricks 建議使用 Apache Spark，以確保欄位定義格式與 Apache Spark 相容。 API 不會驗證資料行規格的正確性。 如果規格與 Apache Spark 不相容，則 Databricks Runtime 可能無法讀取數據表。

使用 PAT 認證使用 Apache Spark 存取 Delta 資料表

以下設定是使用 PAT 認證透過 Apache Spark 讀寫 Unity Catalog 管理及外部 Delta 表的必要條件：

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

替代下列變數：

  • <uc-catalog-name>：Unity Catalog 中包含您資料表的目錄名稱。
  • <token>：用於設定整合的主體之個人存取權杖（PAT）。
  • <workspace-url>：Azure Databricks workspace 網址，包含工作區 ID。 例如： adb-1234567890123456.12.azuredatabricks.net 。

備註

上述套件版本截至本頁最後更新時為最新版本。 可能有更新版本。 確認套件版本是否與你的 Spark 版本相容。

關於如何設定 Apache Spark 以進行雲端物件儲存的更多細節，請參閱 Unity 目錄 OSS 文件。

這很重要

Databricks Runtime 16.4 及以上版本必須讀取、寫入或建立啟用目錄提交的表格。 Databricks Runtime 18.0 及以上版本是啟用或停用現有資料表目錄提交的必要條件。

要建立帶有 目錄提交的受管理 Delta 資料表，請使用以下 SQL：

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported') USING delta;

要建立外部 Delta 資料表，請使用以下 SQL：

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
USING delta
LOCATION <path>;

使用 Apache Spark 使用 OAuth 認證存取 Delta 資料表

Azure Databricks 也支援 OAuth 機器對機器（M2M）認證。 OAuth 會自動處理 Unity 目錄認證的憑證與憑證續期。

外部 Spark 用戶端的 OAuth 認證需要：

  • Unity Catalog Spark 客戶端版本 0.4.1 或更新版本（io.unitycatalog:unitycatalog-spark）
  • Apache Spark 4.0 或更新版本
  • Delta Spark 4.2.0 或更新版本
  • 一位擁有適當許可的OAuth M2M服務負責人。 請參見 使用 OAuth 授權服務主體存取 Azure Databricks。

以下設定是使用 Apache Spark 使用 OAuth 認證建立、讀取或寫入 Unity 目錄管理資料表及外部 Delta 資料表的必要條件：

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.auth.type": "oauth",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.uri": "<oauth-token-endpoint>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientId": "<oauth-client-id>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientSecret": "<oauth-client-secret>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

替代下列變數：

  • <workspace-url>：Azure Databricks workspace 網址，包含工作區 ID。 例如： adb-1234567890123456.12.azuredatabricks.net 。

備註

上述套件版本截至本頁最後更新時為最新版本。 可能有更新版本。 確認套件版本是否與你的 Spark 版本相容。

使用 API 建立 Delta 表

若要使用 Unity 目錄 REST API 建立外部 Delta 數據表，請遵循下列步驟：

步驟 1：對建立數據表 API 提出 POST 要求

使用下列 API 要求在 Unity 目錄中註冊資料表元資料：

curl --location --request POST 'https://<workspace-url>/api/2.0/unity-catalog/tables/' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "<table-name>",
  "catalog_name": "<uc-catalog-name>",
  "schema_name": "<schema-name>",
  "table_type": "EXTERNAL",
  "data_source_format": "DELTA",
  "storage_location": "<path>",
  "columns": [
    {
      "name": "id",
      "type_name": "LONG",
      "type_text": "bigint",
      "type_json": "\"long\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 0,
      "nullable": true
    },
    {
      "name": "name",
      "type_name": "STRING",
      "type_text": "string",
      "type_json": "\"string\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 1,
      "nullable": true
    }
  ]
}'

替代下列變數：

  • <workspace-url>：Azure Databricks工作區的網址
  • <token>：進行 API 呼叫之主體的令牌
  • <uc-catalog-name>：Unity 目錄中將包含外部資料表的目錄名稱
  • <schema-name>：目錄內將建立數據表的架構名稱
  • <table-name>：外部數據表的名稱
  • <path>：資料表數據的完整定位路徑

步驟 2：初始化 Delta 數據表位置

上述 API 呼叫會在 ：[UC] 中註冊數據表，但不會在儲存位置建立 Delta 檔案。 若要初始化數據表位置，請使用 Spark 撰寫空的 Delta 數據表：

此步驟中使用的架構必須完全符合 API 要求中提供的數據行定義。


from pyspark.sql.types import StructType, StructField, StringType, LongType

# Define schema matching your API call
schema = StructType([
    StructField("id", LongType(), True),
    StructField("name", StringType(), True)
])

# Create an empty DataFrame and initialize the Delta table
empty_df = spark.createDataFrame([], schema)
empty_df.write \
    .format("delta") \
    .mode("overwrite") \
    .save("<path>")

備註

針對外部用戶端建立資料表 API 有下列限制：

  • 僅支援外部 Delta 資料表 （"table_type": "EXTERNAL" 和 "data_source_format": "DELTA"）。
  • 只允許下列欄位：
    • name
    • catalog_name
    • schema_name
    • table_type
    • data_source_format
    • columns
    • storage_location
    • properties
  • 不支援欄位遮罩。
  • Last updated on