从 Apache Iceberg 客户端访问 Azure Databricks 表

使用 Apache Iceberg REST 目录从受支持的 Iceberg 客户端（包括 Apache Spark、Apache Flink、Trino 和 Snowflake）读取和写入 Azure Databricks 上注册的 Unity 目录注册表中的表。

有关受支持的集成的完整列表，请参阅 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 REST 目录配置从 Iceberg 客户端读取或写入 Azure Databricks 表的访问权限：

• 为元存储启用外部数据访问。 请参阅在元存储上启用外部数据访问。
• 授予配置集成的主体对包含表的架构的 EXTERNAL USE SCHEMA 特权。 请参阅向主体授权EXTERNAL USE SCHEMA。
• 使用 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 Uniform 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_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>
  • Azure：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 表

下面是建议的配置设置示例，通过连接到 Unity 目录中的 Iceberg REST 目录，允许 Snowflake 读取 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.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>"
  }
}