从 Databricks Unity Catalog 导入元数据

使用 Knowledge Catalog（以前称为 Dataplex Universal Catalog）连接器将元数据从 Databricks Unity Catalog 直接导入 Google Cloud，从而打破数据孤岛，避免在工具之间切换。

此连接器支持托管在Google Cloud、Microsoft Azure 或 Amazon Web Services (AWS) 上的 Databricks Unity Catalog 实例。

下表列出了 Databricks Unity Catalog 连接器捕获的元数据：

类别	已捕获元数据
技术	Metastore 目录 架构 表（托管 Delta、外部、流式、在线、特征、Apache Iceberg REST Catalog [IRC]） 视图（标准视图、物化视图） 卷 函数和过程
可运行	使用情况指标（30 天和 90 天内的查看次数；30 天内的读取次数、写入次数、频繁用户和频繁联接的表） 主键和外键
商务版	标签（对象、数据分类） 数据质量（数据质量监控中的异常值检测结果，以及 Lakehouse 监控中的数据偏移和自定义指标） 数据分析（来自 Lakehouse Monitoring） 联接和关系 表和视图所有者、创建时间和上次更改时间
语义	指标视图（维度、测量、关系映射、认证） 指标视图所有者 指标视图使用情况（30 天和 90 天内的视图；30 天内的读取、写入、频繁用户和频繁联接的表） 显示名称（来自指标视图） 同义词（来自指标视图） Markdown 评论

限制

Databricks Unity Catalog 连接器具有以下限制：

• 不支持沿袭。
• 集成 (Genie API) 不支持语义标记和业务术语库。
• 连接器会导入 Iceberg 表的元数据，但不会自动将导入的条目关联到相应的 Google Cloud Lakehouse Databricks Unity Catalog Iceberg REST Catalog (IRC) 条目。

准备工作

在从 Databricks Unity Catalog 导入元数据之前，请完成以下任务：

1. 授予所需的角色和权限。
2. 启用 Dataplex API 和 BigQuery Data Transfer Service API。
3. 满足 Databricks Unity Catalog 前提条件。
4. 满足网络前提条件。

IAM 角色和权限

如需创建和管理 Knowledge Catalog 连接器作业，您需要拥有授予 Knowledge Catalog 和 BigQuery Data Transfer Service 权限的 Identity and Access Management (IAM) 角色。

如需获得配置 Databricks Unity Catalog 连接器所需的权限，请让您的管理员为您授予以下 IAM 角色：

• 如需创建和管理条目组，您需要拥有项目的 Dataplex Catalog Admin (roles/dataplex.catalogAdmin)、Dataplex Catalog Editor (roles/dataplex.catalogEditor) 或 Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) 角色。
• 如需查看 Databricks Unity Catalog 元数据，请执行以下操作：针对项目的 Dataplex Catalog Viewer (roles/dataplex.catalogViewer)。
• 创建和管理 BigQuery Data Transfer Service 转移作业：项目的 BigQuery Admin (roles/bigquery.admin) 角色。
• 如需在 Cloud Logging 中查看日志，您需要拥有项目的 日志查看器 (roles/logging.viewer) 角色。

您还必须向 BigQuery Data Transfer Service 服务代理 (service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.) 授予以下两个角色：

• 目标条目组或包含该条目组的项目上的 Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter)。此角色允许服务代理将元数据导入条目组 (dataplex.entryGroups.import)。

• 针对包含目标条目组的项目的 Dataplex Entry and EntryLink Owner (roles/dataplex.entryOwner)。此角色可让服务代理导入使用情况、业务和数据质量元数据以及条目链接。它拥有以下权限：

  • dataplex.entryGroups.useDataProfileAspect
  • dataplex.entryGroups.useDataQualityScorecardAspect
  • dataplex.entryGroups.useManagedConnectorTypes
  • dataplex.entryGroups.useReferenceEntryLink
  • dataplex.entryGroups.useSchemaAspect
  • dataplex.entryGroups.useSchemaJoinAspect
  • dataplex.entryGroups.useSchemaJoinEntryLink
  • dataplex.entryGroups.useUsageAspect
  • dataplex.entryLinks.reference

  请在项目（而不仅仅是条目群组）上授予此角色，因为导入操作会检查项目的 dataplex.entryLinks.reference 权限。如果服务代理在项目中没有此权限，则转移作业运行会失败并显示 Permission 'dataplex.entryLinks.reference' denied 等错误，并且不会导入任何元数据。

您可以改为针对包含目标条目组的项目授予 Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) 角色，而无需同时授予这两个角色。此角色包含这两个角色的权限，还允许服务代理创建、删除和管理对项目中所有条目群组的访问权限。

如需详细了解如何授予角色，请参阅管理访问权限。

启用 API

启用 Dataplex API 和 BigQuery Data Transfer Service API。

启用 API

Databricks Unity Catalog 前提条件

用于 Databricks Unity Catalog 连接器的服务主账号必须在 Databricks Unity Catalog 中具有以下权限：

• 对连接器使用的 Databricks SQL 仓库拥有 Can use 权限。
• 对目标目录的 BROWSE 权限，或对目标目录、架构和表或视图的 USE CATALOG、USE SCHEMA 和 SELECT 权限。
• system 目录的 USE CATALOG 权限，以及以下系统架构的 USE SCHEMA 和 SELECT 权限：
  • system.information_schema：读取目录、架构、表、列、卷、例程、约束条件和标记时需要。
  • system.access 和 system.query：可选，导入使用情况指标、使用情况数据分析和查询历史记录联接时需要。
  • system.data_quality_monitoring：可选，导入异常值检测结果时必须提供。
• 可选：对 Lakehouse Monitoring 输出表（TABLE_NAME_profile_metrics 和 TABLE_NAME_drift_metrics）的 USE CATALOG、USE SCHEMA 和 SELECT 权限，用于导入数据分析和偏移指标。

如果您还想针对远程 Databricks 目录运行 SQL 查询或 Spark 作业，请参阅为 Databricks Unity Catalog 设置跨云连接。

网络前提条件

为了让 BigQuery Data Transfer Service 通过专用网络内的专用 IP 地址安全地连接到外部数据库或第三方云数据源，请通过 Private Service Connect 配置网络连接。

如果您使用公共 IP 地址连接到本地环境或云托管实例，则不需要网络连接。

注意： 不支持具有网络连接的私有网域。

配置 Databricks Unity Catalog 连接器

使用 Google Cloud 控制台或 REST API 配置 Databricks Unity Catalog 连接器。

控制台

1. 在 Google Cloud 控制台中，前往 Knowledge Catalog 页面。

   前往 Knowledge Catalog

2. 在导航菜单的管理部分中，点击连接器，然后点击添加连接。

3. 在连接器列表中，选择 Databricks Unity Catalog 卡片。

4. 在数据源详细信息部分，提供 Databricks Unity Catalog 实例的连接详细信息：

   • 对于网络连接，请根据需要选择现有网络连接，或创建一个网络连接。
   • 输入工作区主机、SQL 仓库 HTTP 路径、客户端 ID 和客户端密钥。

   • 在要转移的 Databricks 对象字段中，点击浏览，选择要导入 Knowledge Catalog 的元存储、目录、架构或单个对象（表、视图、卷、函数和过程）。选择 metastore、目录或架构会导入其中的所有对象。

     您也可以手动输入对象，格式为 TYPE:METASTORE[/CATALOG[/SCHEMA[/OBJECT]]]，其中 TYPE 为 METASTORE、CATALOG、SCHEMA、TABLE、VIEW、VOLUME、FUNCTION 或 PROCEDURE（例如 SCHEMA:my_metastore/main/sales）。不支持名称格式。

5. 在目标设置部分中：

   • 点击浏览，然后选择一个现有的 Knowledge Catalog 条目组来存储导入的元数据，或点击创建新条目组。
   • 选择是立即还是稍后设置条目组的权限。 如需允许用户查看导入的元数据，请对条目组设置权限。如果您未在项目级层向 BigQuery Data Transfer Service 服务代理授予 Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter) 角色或 dataplex.entryGroups.import 权限，请在此条目组中授予该角色或权限。您仍必须为项目授予 Dataplex Entry and EntryLink Owner (roles/dataplex.entryOwner) 角色，因为 dataplex.entryLinks.reference 权限是在项目级层检查的。如需了解详情，请参阅 IAM 角色和权限。

6. 在转移配置名称部分的显示名称中，输入元数据导入作业的名称。

7. 在时间表选项部分，配置元数据导入作业的频率。如果您选择按需，则只有在您手动触发作业时，作业才会运行。

8. 可选：在通知选项部分中，为作业失败配置电子邮件或 Pub/Sub 通知。

9. 可选：在高级选项部分中，配置加密设置。如果您选择客户管理的加密密钥 (CMEK)，则该密钥会加密在启动 Knowledge Catalog 元数据导入作业之前暂存的所有临时数据。该密钥不会加密目标 Knowledge Catalog 条目组中的元数据。

10. 点击保存。

REST

使用 projects.locations.transferConfigs.create 方法。 在 TransferConfig 资源中，配置以下字段：

• 将 dataSourceId 字段设置为 "databricks_unity"。
• 在 metadataDestination 字段中，使用目标 Knowledge Catalog 条目组的资源路径填充 dataplexConfiguration.entryGroup 字段：projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID。
• 在 params 字段中，设置以下参数：
  • connector.host（必需）：Databricks 工作区主机名（例如 dbc-a1b2345c-d6e7.cloud.databricks.com）。
  • connector.httpPath（必需）：Databricks SQL 仓库的 HTTP 路径（例如 /sql/1.0/warehouses/a1b2345c67890def）。
  • connector.authentication.oauth.clientId（必需）：Databricks OAuth 客户端 ID。
  • connector.authentication.oauth.clientSecret（必需）：Databricks OAuth 客户端密钥。
  • connector.networkAttachment（可选）：格式为 projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT_ID 的网络连接。
  • assets（必需）：要导入的 Databricks Unity Catalog 对象列表，格式为 TYPE:METASTORE[/CATALOG[/SCHEMA[/OBJECT]]]，例如 ["SCHEMA:my_metastore/main/sales"]。
• 可选：如需将 OAuth 凭证保留在转移作业配置之外，请将其存储在 Secret Manager 中：
  1. 将 connector.authentication.oauth.clientSecret（以及 connector.authentication.oauth.clientId，如果您愿意）设置为 Secret 版本资源名称，格式为 projects/SECRET_PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID，并将这些参数名称添加到 paramConfig.secretManagerManagedParams 字段。
  2. 向包含转移作业配置 (service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.) 的项目的 BigQuery Data Transfer Service 服务代理授予每个 Secret 的 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。Secret 可以位于其他项目中。如果服务代理无法读取 Secret，则运行会在启动前失败，并显示 Failed to retrieve secret ... Permission 'secretmanager.versions.access' denied 等错误。BigQuery Data Transfer Service 会在每次运行开始时读取 Secret，因此，如果您将 VERSION_ID 设置为 latest，则从下次运行开始，系统会使用轮替的 Secret。

以下示例展示了 TransferConfig 请求正文：

{
  "displayName": "databricks-unity-metadata-import",
  "dataSourceId": "databricks_unity",
  "schedule": "every 24 hours",
  "params": {
    "connector.host": "dbc-a1b2345c-d6e7.cloud.databricks.com",
    "connector.httpPath": "/sql/1.0/warehouses/a1b2345c67890def",
    "connector.authentication.oauth.clientId": "CLIENT_ID",
    "connector.authentication.oauth.clientSecret": "CLIENT_SECRET",
    "assets": [
      "SCHEMA:my_metastore/main/sales"
    ]
  },
  "metadataDestination": {
    "dataplexConfiguration": {
      "entryGroup": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID"
    }
  }
}

该作业会根据您的时间表自动运行，您也可以手动触发。

监控 Databricks Unity Catalog 连接器作业

使用Google Cloud 控制台或 REST API 监控 Databricks Unity Catalog 连接器作业。

控制台

1. 在 Google Cloud 控制台的连接器页面上，点击 Databricks Unity Catalog 转移作业的显示名称。
2. 在运行记录标签页上，点击查看详情以查看日志。
3. 如需查看创建的条目，请点击详细信息标签页，然后点击元数据目标条目组链接。

REST

• 如需列出转移作业配置的运行并查看其状态，请使用 projects.locations.transferConfigs.runs.list 方法。

• 每次运行都会通过 ID 为 dts-run-RUN_ID 的元数据导入作业将收集到的元数据导入 Knowledge Catalog。如需查看导入结果（例如创建的条目数），请使用以下查询在 Logging 中过滤作业的日志：

  logName="projects/PROJECT_ID/logs/dataplex.googleapis.com%2Fmetadata_job"
  AND resource.labels.metadata_job_id="dts-run-RUN_ID"
  

• 如需在不使用 Logging 的情况下查看导入结果，请对 projects/PROJECT_ID/locations/LOCATION/metadataJobs/dts-run-RUN_ID 调用 projects.locations.metadataJobs.get 方法。importResult 字段显示已创建、已更新、未更改和已删除的条目和条目链接的数量。

注意： 即使转移作业运行的元数据导入作业以 SUCCEEDED_WITH_ERRORS 结束，转移作业运行也可能会显示 SUCCEEDED 状态，例如，当某个条目因其某个方面过大而被拒绝时。检查元数据导入作业的状态和日志，确认所有条目均已导入。

搜索和查看 Databricks Unity Catalog 元数据

1. 在 Google Cloud 控制台中，前往 Knowledge Catalog 搜索页面。

   转到搜索

2. 在过滤条件面板中，使用项目、系统和类型别名部分过滤 Databricks Unity Catalog 资产。如需过滤所有 Databricks Unity Catalog 元数据，请在系统部分中选择导入的上下文，然后在代管式连接器子部分中选择 Databricks Unity。

3. 在搜索字段中，输入关键字或自然语言搜索查询。例如，如需通过关键字搜索查看所有 Databricks Unity Catalog 资产，请输入 system=DATABRICKS。

   如需详细了解如何搜索资源，请参阅在 Knowledge Catalog 中搜索资源。如需详细了解可在搜索字段中使用的表达式，请参阅 Knowledge Catalog 的搜索语法。

您还可以使用 LookupContext API 检索特定 Databricks Unity Catalog 资源的 LLM 上下文。如需了解详情，请参阅检索数据资产的上下文。

后续步骤

• 了解如何管理连接器作业。