排查 Databricks Unity Catalog 的跨云数据访问问题

本页面介绍了如何排查 Databricks Unity Catalog 的后台元数据刷新和用户身份联合问题，以便进行跨云数据访问。 如需了解一般跨云数据访问问题排查（例如通过专用互连进行连接和路由），请参阅排查跨云数据访问问题。

表为空或在刷新期间未发现

如果目录后台元数据刷新指示成功（例如 Refresh successfully completed），但联合目录中的表未显示或列出表返回 0 项，请检查以下内容：

• EXTERNAL USE SCHEMA 权限：验证 Databricks 服务主体是否已在 Unity Catalog 中获得对目标架构或目录的 EXTERNAL USE SCHEMA 权限。如果没有此权限，后台元数据刷新和查询凭据发放将失败。
• 外部数据访问设置：验证 Databricks Unity Catalog 元存储上是否已启用外部数据访问。
• 外部位置：验证 Databricks Unity Catalog 和表使用的是外部存储位置（例如 Cloud Storage 或 Amazon S3），而不是默认存储。

元数据同步失败或返回 401 Unauthorized

如果后台元数据刷新状态报告错误（例如 401 Unauthorized）或无法发现架构，请验证以下内容：

• 服务主体联合政策：在 Databricks 账号控制台（账号设置 > 安全 > 身份提供方设置 > 联合政策）中，验证服务主体联合政策是否配置如下：
  • 颁发者网址： https://accounts.google.com
  • 主题：目录的 biglake-service-account 服务账号的数字形式唯一 ID（而非其邮箱）。
  • 受众群体： https://accounts.cloud.databricks.com
• Secret Manager 权限：如果使用基于 Secret 的身份验证，请验证 Secret 是否存在于指定的区域位置，以及 biglake-service-account 是否已获得 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。
• 服务主体权限：确保 Databricks 服务主体对目标工作区和目录具有读取权限。

交互式查询失败，并显示“401 未经授权”或令牌验证错误

启用用户身份联合后，交互式查询会动态生成最终用户身份令牌，并根据 Databricks 中的账号级联合政策对其进行验证。如果查询失败并显示 401 Unauthorized 或令牌验证错误，而后台元数据同步正常，请检查以下内容：

• 已配置账号级联合政策：确保在 Databricks 账号控制台中的账号设置 > 安全 > 身份提供方设置 > 联合政策下创建了账号级联合政策（不同于服务主体政策）。
• 区分大小写的受众群体匹配：Databricks 会严格区分大小写地验证 aud（受众群体）声明。验证 Databricks 账号级联合政策中的受众群体字段是否与从目录中检索到的元存储区级 audience 声明 (databricks-METASTORE_ID) 的大小写完全一致。任何大小写不一致（例如，在 databricks- 前缀或 metastore UUID 中）都会导致 Databricks 令牌验证拒绝查询，并显示 401 Unauthorized。
• 颁发者网址：验证颁发者网址是否与目录中的 issuer-url 声明完全匹配：https://www.gstatic.com/biglake/federation/organizations/ORGANIZATION_ID。
• Metastore 受众群体可用性：只有在第一个后台元数据刷新周期完成后（通常在 5 分钟内），系统才会填充 metastore 范围的 audience 声明。如果您使用占位值配置政策，或者在第一个刷新周期完成之前配置政策，查询将会失败。在配置政策之前，请运行 gcloud biglake iceberg catalogs describe 以验证 audience 声明是否已填充。