从 Apache Iceberg 客户端访问 Azure Databricks 表

Apache Iceberg REST 目录允许支持的客户端（如 Apache Spark、Apache Flink 和 Trino）在 Azure Databricks 上读取和写入 Unity 目录注册的 Iceberg 表。

有关受支持的集成的完整列表，请参阅 Unity 目录集成。

使用 Unity 目录 Iceberg 目录终结点

Unity 目录提供 Iceberg REST 目录 API 规范的实现。

使用终结点 /api/2.1/unity-catalog/iceberg-rest 配置访问权限。 有关使用此 REST API 的详细信息，请参阅 Iceberg REST API 规范 。

要求

Azure Databricks 支持通过 Iceberg REST 目录访问 Unity Catalog 中的表。 必须在工作区启用 Unity Catalog 才能使用这些接口。 下表类型可通过 Iceberg REST 目录访问：

通过 Iceberg REST 目录 API 读取时，外部 Iceberg 表不会自动刷新。 若要刷新，必须运行 REFRESH FOREIGN TABLE 才能读取最新的快照。 不支持对外部 Iceberg 表进行凭证售卖。

必须完成以下配置步骤，才能使用 Iceberg REST 目录配置从 Iceberg 客户端读取或写入 Azure Databricks 表的访问权限：

• 为元存储启用 外部数据访问 。 请参阅 在元存储上启用外部数据访问。
• 向配置集成的主体授予对包含表的架构的 EXTERNAL USE SCHEMA 权限。 请参阅 授予主体 Unity 目录特权。
• 使用 Azure Databricks 个人访问令牌或 OAuth 进行身份验证。 请参阅 授权访问 Azure Databricks 资源。

将 Iceberg 表与 Apache Spark 配合使用

以下示例演示如何使用 OAuth 身份验证将 Apache Spark 配置为通过 Iceberg REST 目录 API 访问 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 会话中分配目录的名称。
• <workspace-url>：Azure Databricks 工作区 URL。
• <oauth_client_id>：身份验证主体的 OAuth 客户端 ID。
• <oauth_client_secret>：身份验证主体的 OAuth 客户端密码。

使用这些配置，可以使用 Apache Spark 查询 Unity 目录中的表。 为了访问多个目录中的表，必须单独配置每个目录。

使用 Spark 配置查询 Unity Catalog 中的表时，请记住以下几点：

• 只有在运行"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>
  • 天蓝色： org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
  • GCP：org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

  有关详细信息，请参阅 适用于 Spark 的 Iceberg AWS 集成的文档。

  注意

  从 Azure Databricks 访问 Iceberg 表时，不需要这些配置。 不支持将外部 Iceberg JAR 加载到 Azure Databricks 群集。

使用 Snowflake 访问 Azure Databricks 表

下面是 Snowflake 通过连接到 Unity 目录中的 Iceberg REST 目录来访问 Azure Databricks 表的配置设置示例：

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>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

替换以下变量：

• <catalog-integration-name>: 要为注册到 Snowflake 的目录分配的名称。
• <uc-schema-name>：需要访问的 Unity Catalog 中架构的名称。
• <uc-catalog-name>：需要访问的 Unity Catalog 中目录的名称。
• <workspace-url>：Azure Databricks 工作区 URL。
• <token>: 配置集成的主体的 PAT 令牌。

将 Azure Databricks 表与 PyIceberg 配合使用

下面是一个配置设置示例，通过连接到 Unity 目录中的 Iceberg REST 目录，允许 PyIceberg 访问 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。
• <uc-catalog-name>：需要访问的 Unity Catalog 中目录的名称。
• <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.chinacloudapi.cn/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.chinacloudapi.cn": "<temporary-sas-token>"
  }
}