转换到知识目录中的业务术语库

本文档提供了相关说明，可帮助您一步到位地从支持 Data Catalog 元数据的业务术语库预览版迁移到 Knowledge Catalog（以前称为 Dataplex Universal Catalog）中的正式版业务术语库。迁移到正式版后，您可以使用增强的功能并与 Knowledge Catalog 元数据进行更深入的集成，从而获得更高的稳定性、新功能和全面的生产支持。此过程会自动更新您的术语表，以支持 Knowledge Catalog 元数据。

注意： 如果您已开始使用手动流程迁移术语库，并想查看相关说明，请参阅手动转换到 Knowledge Catalog 中的业务术语库。

准备工作

1. 安装 gcloud 或 Python 软件包。 对您的用户账号和 Python 库使用的应用默认凭证 (ADC) 进行身份验证。运行以下命令，并按照基于浏览器的提示操作：

   gcloud init
   gcloud auth login
   gcloud auth application-default login
   

2. 启用以下 API：

   • Dataplex API
   • Data Catalog API
   • Cloud Resource Manager API
   • Cloud Storage API

3. 在您的任何项目中创建一个或多个 Cloud Storage 存储桶。这些存储桶将用作导入文件的临时位置。您提供的存储桶越多，导入速度就越快。向运行迁移的服务账号授予 Storage Admin IAM 角色：

   service-MIGRATION_PROJECT_ID@gcp-sa-dataplex.

   将 MIGRATION_PROJECT_ID 替换为要从中迁移术语库的项目。

4. 设置代码库：

   1. 克隆代码库：

      git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
      cd dataplex-labs/dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import
      

   2. 安装所需的软件包：

      pip3 install -r requirements.txt
      cd migration
      

      注意： 如果您在安装软件包时遇到任何问题，请按照相关步骤创建新的 Python 虚拟环境。

所需的角色

如需获得将术语表从 Data Catalog 迁移到 Knowledge Catalog 所需的权限，请让您的管理员为您授予以下 IAM 角色：

• 针对项目的 Data Catalog Glossary Owner (roles/datacatalog.glossaryOwner)
• 针对您的项目的 Dataplex Administrator (roles/dataplex.admin)

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

这些预定义角色包含将术语库从 Data Catalog 迁移到 Knowledge Catalog 所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需将术语库从 Data Catalog 迁移到 Knowledge Catalog，您需要具备以下权限：

• datacatalog.glossaries.get 对您要从中迁移词库的项目具有的权限
• datacatalog.glossaries.list 对您要从中迁移词库的项目具有的权限
• dataplex.glossaries.create 对在 Knowledge Catalog 中创建术语库的项目具有此权限
• dataplex.glossaries.update 在 Knowledge Catalog 中将更新术语库的项目上

您也可以使用自定义角色或其他预定义角色来获取这些权限。

如需详细了解 Knowledge Catalog Identity and Access Management (IAM)，请参阅使用 IAM 管理访问权限。

运行迁移脚本

python3 run.py --project=PROJECT_ID --buckets=BUCKET1,BUCKET2

替换以下内容：

• PROJECT_ID：要迁移的项目的 ID。此项目还用于结算和配额归因，以确定脚本生成的 API 调用。

• BUCKET1 和 BUCKET2：将用于导入的 Cloud Storage 存储桶 ID。

  您可以提供一个或多个存储分区。对于存储桶实参，请提供以英文逗号分隔且不含空格的存储桶名称列表（例如 --buckets=bucket-one,bucket-two）。存储桶与词汇表之间无需一对一映射；脚本会并行运行导入作业，从而加快迁移速度。

如果权限问题导致脚本无法自动发现组织 ID，请使用 --orgIds 标志指定脚本可用于搜索与词汇表术语相关联的数据资产的组织。

注意： 请勿修改导出的 JSON 文件。该脚本会生成 Dataplex 导入 API 所需格式的文件；修改格式可能会导致导入作业失败。

迁移中的范围术语表

如需仅迁移特定术语表，请提供相应术语表的网址来定义其范围。

python3 run.py --project=PROJECT_ID --buckets=BUCKET1,BUCKET2 --glossaries="GLOSSARY_URL1","GLOSSARY_URL2"

将 GLOSSARY_URL1（和 GLOSSARY_URL2）替换为您要迁移的术语表的完整网址，这些网址应与Google Cloud 控制台中显示的网址一致。如果您使用此标志指定词库，系统会根据网址确定源项目，而 --project 标志仅用于结算。

示例：https://console.cloud.google.com/datacatalog/glossaries/projects/my-project/locations/us-central1/entryGroups/my-entry-group/glossaries/my-glossary

迁移运行时，导入作业的数量可能少于导出的词汇表数量。如果直接创建不需要后台导入作业的空词库，就会发生这种情况。

继续执行迁移以处理导入作业失败

迁移后如果存在文件，则表示某些导入作业失败。如需恢复迁移，请运行以下命令：

python3 run.py --project=PROJECT_ID --buckets=BUCKET1,BUCKET2 --resume-import

如果遇到失败情况，请再次运行 resume 命令。该脚本仅处理未成功导入和删除的文件。

该脚本会强制执行词条链接和词汇表间链接的依赖项检查。只有在成功导入条目链接文件的父词汇表后，才能导入该条目链接文件。同样，只有在成功导入所有被引用的术语后，才能导入术语之间的链接。

注意： 随机 ID 可能会附加到日志或生成的文件中的词汇表、条目链接和作业名称中。这些 ID 用于确保内部后端唯一性，不会影响最终迁移的词库的名称或结构。

问题排查

本部分提供了常见错误的解决方案。

• “权限遭拒”/ 403 错误：确保用户或服务账号对目标项目具有 Dataplex Editor 角色，对源项目具有 Dataplex Viewer 角色。

• ModuleNotFoundError：确保您已激活 Python 虚拟环境，并使用 pip3 install -r requirements.txt 安装了必需的软件包。

• TimeoutError / ssl.SSLError：这些网络级错误可能是由防火墙、代理或连接速度缓慢引起的。该脚本的超时时间为 5 分钟 - 如果问题持续存在，可能需要检查本地网络配置。

• 找不到方法（无法提取条目）：此错误通常表示您的用户项目未获授权来调用 API，从而导致无法检索必要的条目。