从 Delta 客户端访问 Databricks 的数据表

本页介绍如何使用 Unity REST API 从外部 Delta 客户端创建、读取和写入 Unity 目录托管表和外部表。 有关受支持的集成的完整列表，请参阅 Unity 目录集成。

使用 Unity REST API 创建、读取和写入

Unity REST API 提供外部客户端对注册到 Unity 目录的表的创建、读取和写入访问权限。 使用 工作区 URL 作为端点配置访问权限。 下表类型是可访问的：

* 支持包含 目录提交的托管 Delta 表。

要求

Azure Databricks 支持 Unity REST API 访问作为 Unity Catalog 的一部分的表。 必须在工作区中启用 Unity Catalog 才能使用这些终结点。

还必须完成以下配置步骤，以使用 Unity REST API 配置对 Delta 客户端表的访问：

• 为元存储启用 外部数据访问 。 请参阅 在元存储上启用外部数据访问。
• 向主体授予外部访问架构中包含对象的EXTERNAL USE SCHEMA权限。 请参阅 为实体授予 Unity Catalog 权限。
• 通过路径访问的外部表：向主体授予对包含表路径的外部位置的EXTERNAL USE LOCATION权限。 请参阅 为实体授予 Unity Catalog 权限。
• 确保主体具有相关的权限：
  • SELECT 用于读取的表
  • MODIFY 用于写入的表
  • CREATE 用于创建表的架构
  • 对于对托管 Delta 表的外部写入，请验证要写入的表是否已启用 目录提交 。
• 使用以下方法之一进行身份验证：
  • 个人访问令牌（PAT）：请参阅 授权访问 Azure Databricks 资源。
  • OAuth 机器对机器（M2M）身份验证：支持自动凭据和令牌刷新，用于运行超过 >1 小时的 Spark 作业。 请参阅 使用 OAuth 授权服务主体访问 Azure Databricks。

局限性

• 目前不支持通过 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 表和外部 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 工作区 URL，包括工作区 ID。 例如，adb-1234567890123456.12.databricks.azure.cn。

有关为云对象存储配置 Apache Spark 的其他详细信息，请参阅 Unity 目录 OSS 文档。

若要使用 目录提交创建托管 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>;

使用 OAuth 身份验证通过 Apache Spark 访问 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。

若要使用 OAuth 身份验证通过 Apache Spark 创建、读取或写入 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"

替换以下变量：

• <uc-catalog-name>：Unity Catalog 中包含表的目录的名称。

• <oauth-token-endpoint>：OAuth 令牌终结点 URL。 构造此 URL：

  1. 找到Azure Databricks帐户 ID。 请参阅查找帐户 ID。
  2. 使用以下格式： https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/v1/token

• <oauth-client-id>：服务主体的 OAuth 客户端 ID。 请参阅 使用 OAuth 授权服务主体访问 Azure Databricks。

• <oauth-client-secret>：服务主体的 OAuth 客户端密码。 请参阅 使用 OAuth 授权服务主体访问 Azure Databricks。

• <workspace-url>：Azure Databricks 工作区 URL，包括工作区 ID。 例如，adb-1234567890123456.12.databricks.azure.cn。

使用 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工作区的 URL
• <token>：用于标识进行 API 调用主体的令牌
• <uc-catalog-name>：将包含外部表的目录在 Unity Catalog 中的名称
• <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>")