从 Data Catalog 转换到 Knowledge Catalog

Knowledge Catalog（以前称为 Dataplex Universal Catalog）取代了 Data Catalog，可提供更复杂的元数据管理、高级数据治理功能、更强大的数据搜索功能、更简单的访问权限控制，以及可简化开发的统一 API。 本文档将介绍如何将 Data Catalog 内容和使用情况迁移到 Knowledge Catalog。

如果您是刚开始使用目录，请先从 Knowledge Catalog 入手，将其配置为默认目录体验。

Knowledge Catalog 具有统一的网页界面和 API。转换到 Knowledge Catalog 后，现有和未来的工作负载以及用户能够从其增强的功能和能力中受益。如需了解详情，请参阅 Knowledge Catalog 中的元数据简介。

如需比较 Knowledge Catalog 和 Data Catalog，请参阅 Knowledge Catalog 与 Data Catalog 的比较。

准备工作

在开始转换之前，请查看 Knowledge Catalog 不支持的元数据管理功能。

注意： 政策标记和政策标记分类用于 BigQuery 中的列级访问权限控制和动态数据遮盖，未被弃用。政策标记管理器服务将继续通过 datacatalog.googleapis.com 端点提供，并且在使用 BigQuery 政策标记的项目中，Data Catalog API (datacatalog.googleapis.com) 必须保持启用状态。

转换概览

Google Cloud 控制台中的管理到 Knowledge Catalog 的转换页面提供了一个用于管理转换的单一访问点。

本部分将介绍各种过渡方案，并概述每种方案的过渡流程。

如果您在 Data Catalog 中没有自定义元数据，或者您从未使用过 Data Catalog

如果您使用的是 Data Catalog，但没有自定义元数据（例如标记、标记模板、自定义条目或条目组），或者您从未使用过 Data Catalog，请通过将默认目录界面体验设为 Knowledge Catalog 来完成转换。

注意：如果您在 Data Catalog 中没有自定义元数据，或者您从未使用过 Data Catalog，请跳过本文档中所述的所有其他任务。

如果您有 Data Catalog 自定义元数据或程序化工作负载

如果您使用的是包含自定义元数据（例如标记、标记模板、自定义条目或条目组）的 Data Catalog，Knowledge Catalog 可以自动以 read-only 形式导入此自定义元数据。如需启用此功能，需要按照准备阶段中的说明进行配置更改。

第二阶段是升级阶段，在此阶段，自定义元数据的有效状态 (read-write) 会移至 Knowledge Catalog。在此阶段，您还必须更新任何程序化工作负载（例如 API、客户端库、Terraform 模块和 Google Cloud CLI 命令），以与 Knowledge Catalog 进行交互。

以下内容详细介绍了转换过程的各个阶段：

1. 准备阶段：执行必要的配置任务，以便 Data Catalog 内容以 read-only 形式同时在 Knowledge Catalog 中提供。在此阶段，Data Catalog 仍是元数据内容的权威来源。

   准备阶段包括以下任务：

   1. 将 Data Catalog 非公开标记模板更新为公开。
   2. 为自定义元数据配置 Knowledge Catalog IAM 权限。

   如需了解详情，请参阅准备阶段。

2. 升级阶段：将目录使用情况和自定义元数据的有效状态 (read-write) 移至 Knowledge Catalog。

   升级阶段包括以下任务：

   1. 将默认目录界面体验设为 Knowledge Catalog。
   2. 将 Data Catalog 自定义元数据升级到 Knowledge Catalog。
   3. 更新程序化工作负载。

   完成升级阶段后，Knowledge Catalog 将成为所有元数据的权威来源，您无需再使用 Data Catalog。

   如需了解详情，请参阅升级阶段。

所需的角色

如需获得从 Data Catalog 转换到 Knowledge Catalog 所需的权限，请授予资源的以下 IAM 角色：

• 将非公开标记模板更新为公开：Data Catalog TagTemplate Owner (roles/datacatalog.tagTemplateOwner)

  此预定义角色可提供将非公开标记模板更新为公开所需的 datacatalog.tagTemplates.update 权限。

• 将默认目录界面体验设为 Knowledge Catalog：DataCatalog Migration Config Admin (roles/datacatalog.migrationConfigAdmin)

  此预定义角色可提供设置默认目录界面体验所需的 datacatalog.migrationConfig.set 权限。

• 将 Data Catalog 公开标记模板升级到 Knowledge Catalog：Data Catalog TagTemplate Owner (roles/datacatalog.tagTemplateOwner)

  此预定义角色可提供升级公开标记模板所需的 datacatalog.tagTemplates.update 权限。

• 将 Data Catalog 条目组升级到 Knowledge Catalog：DataCatalog EntryGroup Owner (roles/datacatalog.entryGroupOwner)

  此预定义角色可提供升级条目组所需的 datacatalog.entryGroups.update 权限。

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

准备阶段

注意：仅当您有 Data Catalog 自定义元数据或程序化工作负载时，才需要执行本部分中所述的任务。

此阶段涉及的任务是让 Data Catalog 元数据内容以 read-only 模式同时在 Knowledge Catalog 中提供。

以下是准备阶段需要记住的一些要点：

• Data Catalog 仍是您的自定义元数据的权威来源。
• 在您完成准备阶段之前，Knowledge Catalog 搜索可能不包含所有 Data Catalog 公开标记模板和标记。

详细了解如何在 Knowledge Catalog 中同时提供 Data Catalog 元数据

Data Catalog 自定义条目组、条目、标记和公开标记模板会自动在 Knowledge Catalog 中以 read-only 资源的形式提供。

下表显示了 Data Catalog 资源同时在 Knowledge Catalog 中提供时，Data Catalog 资源与 Knowledge Catalog 资源之间的映射关系：

Data Catalog 与 Knowledge Catalog 之间的映射

Data Catalog 资源	对应的 Knowledge Catalog 资源	说明
标记模板	切面类型（全局）	Data Catalog 中的标记模板属于区域级资源。其内容会作为全局切面类型同时在 Knowledge Catalog 中提供。这是为了保留标记与标记模板之间的跨区域级引用。全局切面类型的定义会复制到所有 Google Cloud 区域。 Schema 等标准概念由 Knowledge Catalog 提供的系统切面类型表示。如需了解详情，请参阅切面类型的类别。
标记	可选切面	标记会作为可选切面同时在 Knowledge Catalog 中提供。如需了解详情，请参阅切面类别。
条目组	条目组	系统条目的条目组是在 Knowledge Catalog 中按项目和区域建立的。在 Data Catalog 中创建的条目组会同时在 Knowledge Catalog 中提供。
自定义条目	自定义条目	Data Catalog 中的所有自定义条目都会作为 GenericEntryType 条目同时在 Knowledge Catalog 中提供。如需了解详情，请参阅条目类型的类别。
系统条目 (Google Cloud)	系统条目所需的切面	描述系统条目的元数据（例如 BigQuery 表的 Schema）会捕获在系统定义的切面类型的必需切面中。

注意：通常，对 Data Catalog 内容的更新会在 10 分钟内传播到 Knowledge Catalog。在某些情况下，可能需要更长时间。为了验证数据一致性，我们建议您停止对 Data Catalog 执行所有写入操作，并在使用 Knowledge Catalog 资源前，根据 Data Catalog 资源或原始来源系统对其进行验证。

将 Data Catalog 非公开标记模板更新为公开

注意：仅当您在 Data Catalog 中使用非公开标记模板和标记时，才需要执行此任务。
数据管家或数据管理员必须执行此任务。

Knowledge Catalog 不支持非公开切面的概念（与非公开标记相对应）。因此，非公开标记模板和标记不会同时在 Knowledge Catalog 中提供。如需在 Knowledge Catalog 中传播非公开标记模板和标记，您必须将其更新为公开。

在继续操作之前，请查看非公开标记模板的结构，以验证其结构和元数据是否与公开标记的公开范围一致。

如需将非公开标记模板和标记更新为公开，请按照以下步骤操作：

控制台

1. 在 Google Cloud 控制台中，前往代码模板页面。

   转到“标记模板”

2. 点击管理到 Knowledge Catalog 的转换。

3. 点击非公开标记模板标签页。

4. 点击管理标记模板。

5. 在标记模板页面上，点击要更新的非公开标记模板。

6. 在模板详情页面上，点击修改。

7. 在公开范围部分中，选择公开。

8. 点击更新。

REST

如需将非公开标记模板更新为公开，请使用 tagTemplates.patch 方法。

为自定义元数据配置 Knowledge Catalog IAM 权限

Knowledge Catalog 切面类型和代表 Data Catalog 中的标记模板和条目组的自定义条目组不会继承原始 Data Catalog IAM 权限。Knowledge Catalog 和 Data Catalog 所需的特定 IAM 权限也有所不同。

例如，如果您想使用传播的切面类型（代表 Data Catalog 标记模板）创建切面，则必须为该切面类型配置必要的 IAM 权限。同样，在注入自定义元数据时，如需在传播的自定义条目组中创建自定义条目，您必须为该条目组配置必要的 IAM 权限。

如果您使用 Data Catalog IAM 角色在项目级或更高级管理 Data Catalog 中的访问权限，则系统会自动添加必要的 Knowledge Catalog 权限。不过，如果您使用的是自定义角色或直接向特定资源分配 IAM 角色，则必须手动为这些特定切面和自定义条目组配置 Knowledge Catalog 权限。

如需详细了解 Data Catalog 中的 IAM 权限与 Knowledge Catalog 中的 IAM 权限之间的对应关系，请参阅 Data Catalog 与 Knowledge Catalog 之间的 IAM 权限映射。

如需为切面类型和自定义条目组配置必要的 Knowledge Catalog IAM 权限，请按照以下步骤操作：

控制台

1. 在 Google Cloud 控制台中，前往代码模板页面。

   转到“标记模板”

2. 点击管理到 Knowledge Catalog 的转换。

3. 点击 Dataplex IAM 权限标签页。

4. 如需为切面类型配置 Knowledge Catalog IAM 权限，请点击切面类型和标记模板。

   1. 对于从 Data Catalog 传播的标记模板，请点击 > 权限。

   2. 点击添加主账号。

   3. 添加新主账号，并分配所需的角色。

   4. 点击保存。

5. 如需为条目组配置 Knowledge Catalog IAM 权限，请点击条目组。

   1. 对于从 Data Catalog 传播的条目组，请点击 > 权限。

   2. 点击添加主账号。

   3. 添加新主账号，并分配所需的角色。

   4. 点击保存。

REST

如需为切面类型配置 Knowledge Catalog IAM 权限，请使用 aspectTypes.setIamPolicy 方法。

如需为条目组配置 Knowledge Catalog IAM 权限，请使用 entryGroups.setIamPolicy 方法。

升级阶段

注意：仅当您有 Data Catalog 自定义元数据或程序化工作负载时，才需要执行本部分中所述的任务。

此阶段涉及的任务是将 Data Catalog 自定义元数据的有效状态 (read-write) 移至 Knowledge Catalog。

在升级阶段，请务必注意以下几点：

• 您可以在 Knowledge Catalog 中发现和读取 Data Catalog 和 Knowledge Catalog 元数据。
• 如需在 Google Cloud 控制台中更新元数据，您将被重定向到其来源。例如，如果您要更新 Data Catalog 标记模板，系统会将您重定向到 Data Catalog 中的标记模板页面。

将默认目录界面体验设为 Knowledge Catalog

注意：对于 Google Cloud 组织，组织管理员必须在组织级层配置此设置。您还可以为自己的项目配置此设置，而不会影响整个组织的设置。对于没有组织的项目，项目管理员必须为单个项目配置此设置。

将默认目录界面体验设为 Knowledge Catalog 意味着以下情况：

• 网页界面会建议您在 Knowledge Catalog 中创建新资源。例如，系统默认显示创建切面类型（而非创建标记模板）和创建条目组 (Knowledge Catalog)（而非创建条目组 [Data Catalog]）。

• 将默认目录界面体验设为 Knowledge Catalog 通常是单向操作。不过，在例外情况下，Knowledge Catalog 可让您还原更改，例如，当您想要将默认目录界面体验切换回 Data Catalog 时。如果您恢复更改，将无法在 Data Catalog 网页界面中访问 Knowledge Catalog 中创建的任何内容。

如需将默认目录界面体验设为 Knowledge Catalog，请按照以下步骤操作：

控制台

1. 在 Google Cloud 控制台中，前往代码模板页面。

   转到“标记模板”

2. 点击管理到 Knowledge Catalog 的转换。

3. 点击默认目录界面体验标签页。

4. 点击将默认目录界面体验设为 Knowledge Catalog。

REST

如需将默认目录界面体验设为 Knowledge Catalog，请使用 setConfig 方法。

将 Data Catalog 自定义元数据升级到 Knowledge Catalog

注意：数据管理员、数据管家或数据工程师必须执行此任务。

您可以将 Data Catalog 公开标记模板和自定义条目组升级到 Knowledge Catalog。请确保您单独升级每个标记模板和自定义条目组。

警告：升级操作是无法撤消的。将现有 Data Catalog 标记模板和条目组升级到 Knowledge Catalog 后，您将无法在 Data Catalog 中更新它们。不过，您可以在 Data Catalog 中删除它们，因为这不会影响升级到 Knowledge Catalog 的版本。

以下内容总结了升级流程：

• 效果

  • 将资源的有效状态从 Data Catalog 转移到 Knowledge Catalog。升级后，如需修改资源或访问其当前状态，您必须使用 Knowledge Catalog。

• 数据内容和流程方面的变化

  • 在 Data Catalog 中将资源标记为 read-only。
  • 在 Knowledge Catalog 中将资源标记为 read-write。
  • 停止同时提供此资源。

• 依赖项

  • 升级代码模板时，使用该模板的所有标记也会一并升级。
  • 升级条目组时，也会升级该组中的所有条目。
  • 升级条目不会影响其标记和相应标记模板的升级状态。

在升级之前，如需修改条目的业务上下文（例如 overview、contacts），您可以同时使用 Data Catalog API 和 Dataplex API。升级后，只能使用 Dataplex API。

下文介绍了带标记的自定义 Data Catalog 条目允许执行的操作，具体取决于相关自定义条目组和标记模板的升级状态：

• 当标记模板在 Data Catalog 中处于有效状态时，您可以使用该标记模板创建标记。将代码模板升级到 Knowledge Catalog 后，您将无法使用该模板在 Data Catalog 中创建标记。
• 只有在升级从 Data Catalog 标记模板传播的切面类型后，您才能使用这些切面类型创建切面。

如需将 Data Catalog 标记模板和自定义条目组升级到 Knowledge Catalog，请按照以下步骤操作：

控制台

1. 在 Google Cloud 控制台中，前往代码模板页面。

   转到“标记模板”

2. 点击管理到 Knowledge Catalog 的转换。

3. 点击升级到 Knowledge Catalog 标签页。

4. 如需将 Data Catalog 标记模板升级到 Knowledge Catalog，请点击查看切面类型和标记模板。

   1. 选择要升级的标记模板。

   2. 点击升级。

   3. 在确认对话框中，点击确认。

5. 如需将 Data Catalog 自定义条目组升级到 Knowledge Catalog，请点击查看条目组。

   1. 选择要升级的入口组。

   2. 点击升级。

   3. 在确认对话框中，点击确认。

REST

如需将 Data Catalog 标记模板和自定义条目组升级到 Knowledge Catalog，请使用 tagTemplates.patch 方法。

完成升级阶段后，Knowledge Catalog 将成为所有元数据的权威来源，您无需再使用 Data Catalog。

注意： 升级后，所有 Data Catalog 更改可能需要短暂延迟才能反映在 Knowledge Catalog 中。为了验证时间关键型工作负载中的数据一致性，我们建议您在使用 Knowledge Catalog 资源之前，先根据 Data Catalog 资源或原始来源系统对其进行验证。

更新程序化工作负载

Knowledge Catalog 随附了新的 API、客户端库、Terraform 模块和 Google Cloud CLI 命令。因此，您必须将使用 Data Catalog 的现有程序化工作负载更新为 Knowledge Catalog。请参阅 Knowledge Catalog 的代码示例。

确保在更新程序化工作负载的同时升级依赖资源，例如标记模板和自定义条目组。这是必要的，因为升级操作会将资源的有效 (read-write) 状态从 Data Catalog 移至 Knowledge Catalog。

以下是更新程序化工作负载以与 Knowledge Catalog 进行交互并协调升级依赖资源的示例序列：

1. 如果您的工作负载可以容忍最终一致性，请将工作负载的 read 操作迁移到 Knowledge Catalog。

2. 将执行标记 write 操作的工作负载移至 Knowledge Catalog，并协调升级其相应的标记模板。

3. 将执行自定义注入 write 操作的工作负载移至 Knowledge Catalog，并协调升级相应的自定义条目组。

如果您需要将更新工作负载与升级相应资源分离，请考虑在工作负载中实现逻辑，以根据资源升级状态将 read-write 路由到 Data Catalog 或 Knowledge Catalog。因此，工作负载的运行将不受相关资源升级状态的影响。

注意： Knowledge Catalog 不支持使用 Terraform 管理自定义条目和切面。您可以改为使用托管式连接流水线或元数据导入 API 方法以程序化方式大规模管理自定义元数据。

后续步骤

• 详细了解 Knowledge Catalog 中的元数据。
• 请参阅将 Data Catalog API 方法映射到 Knowledge Catalog。
• 了解如何在 Knowledge Catalog 中搜索资源。
• 了解如何管理切面和丰富元数据。
• 了解如何管理条目和注入自定义来源。
• 请参阅 Dataplex API 参考文档。