从 Google 表格导入条目链接

本文档介绍了如何使用条目链接导入实用程序将条目链接（术语表术语与数据资产之间的关系，包括 definition、related 和 synonym 条目链接类型）从 Google 表格批量导入到 Knowledge Catalog（以前称为 Dataplex Universal Catalog）。

准备工作

在将条目链接导入 Knowledge Catalog 之前，请完成以下前提条件。

设置服务帐号

如需使用 Google 表格运行导入实用程序，您必须设置一个服务账号，该账号具有访问 Google Sheets API 和模拟用户凭据所需的权限：

1. 确定或创建服务帐号。

   在运行导入实用程序的项目中选择现有服务帐号或创建新服务账号。如需了解详情，请参阅 创建服务账号。 记下服务帐号电子邮件地址 （例如， SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com）。

2. 配置服务帐号模拟。

   如需在本地运行导入实用程序脚本，您的用户账号必须具有模拟服务帐号的权限。向服务帐号授予用户账号的 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

   如需了解详情，请参阅 管理对服务账号的访问权限。

3. 向服务帐号授予对 Google 表格的 Editor 访问权限。

   打开要用于导入过程的 Google 表格，点击共享， 然后将服务帐号电子邮件地址添加为 Editor。此权限可让服务帐号从您的表格中读取数据或向其中写入数据。

创建 Cloud Storage 存储桶

创建一个 Cloud Storage 存储桶，用作导入文件的 暂存区。

所需的角色

为确保服务帐号具有从 Google 表格导入条目链接所需的 权限， 请让管理员向服务帐号授予 以下 IAM 角色：

重要提示：您必须向服务帐号（而不是向您的用户账号）授予这些角色。如果未能向正确的主账号授予这些角色，可能会导致权限错误。

• Dataplex Administrator (roles/dataplex.admin) 针对项目的
• Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 针对项目的
• Dataplex Catalog Editor (roles/dataplex.catalogEditor) 针对项目的
• Storage Object Admin (roles/storage.objectAdmin) 针对 Cloud Storage 存储桶
• Storage Object Creator (roles/storage.objectCreator) 针对 Cloud Storage 存储桶

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

您的管理员还可以通过自定义角色或其他预定义角色向服务帐号授予所需的权限。

启用 API

如需导入条目链接，请在项目中启用以下 API：

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您 创建了项目，则可能已通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。 了解如何授予角色。

启用 API

设置 Git 代码库

克隆 dataplex-labs 代码库：

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

安装依赖项

安装所需的 Python 依赖项：

pip3 install -r requirements.txt
cd dataplex-glossary

如果您在软件包安装过程中遇到任何问题， 请设置新的 Python 开发环境。

进行身份验证并配置服务帐号模拟

初始化 Google Cloud CLI，并使用应用默认凭据 (ADC) 通过服务帐号模拟进行身份验证：

# Set your service account email address
SA_EMAIL="SERVICE_ACCOUNT_EMAIL"

# Authenticate ADC using service account impersonation and required scopes
gcloud init
gcloud auth login
gcloud auth application-default login \
  --impersonate-service-account="${SA_EMAIL}" \
  --scopes="https://www.googleapis.com/auth/spreadsheets"

将 SERVICE_ACCOUNT_EMAIL 替换为服务帐号电子邮件 ID。 例如：

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

跨项目导入要求

如需跨多个 Google Cloud 项目导入条目链接，请确保您的 配置满足以下要求，然后再运行导入 实用程序：

• 配置跨项目 IAM 权限：执行导入脚本的服务帐号必须在所有目标项目中具有足够的权限。

• 验证条目是否存在：在运行导入之前，目标条目必须已存在于各自的 Knowledge Catalog 项目中。

• 向 Knowledge Catalog 服务代理授予 Cloud Storage 存储桶访问权限：每个目标项目中的 Knowledge Catalog 服务账号都需要访问您的 Cloud Storage 存储桶。

创建 Google 表格并设置其结构以进行导入

如需成功运行批量导入，您必须使用精确的列架构创建一个新的 Google 表格，以便导入实用程序能够成功解析和验证您的元数据字段。确保您已向服务帐号授予对 Google 表格的 Editor 访问权限。

表格的第一行必须包含以下完全区分大小写的架构标头：

列标题	必填或可选	说明
entry_link_type	必需	值必须为 definition、related 或 synonym。
source_entry	必需	源条目的完整资源路径，格式为： projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
target_entry	必需	目标条目的完整资源路径，格式为： projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
source_path	可选	定义链接的列或字段路径（例如， Schema.column_name）。

设置环境变量

设置以下环境变量：

# Set your Google Sheet URL
export SPREADSHEET_URL="GOOGLE_SHEET_URL"

# Set your bucket name
export BUCKETS="COMMA_SEPARATED_LIST_OF_BUCKETS"

# Set the project ID
export USER_PROJECT="USER_PROJECT"

从 Google 表格导入条目链接

如需将条目链接从 Google 表格导入到 Knowledge Catalog，请运行 entrylinks-import.py 脚本：

cd import
python3 entrylinks-import.py \
  --spreadsheet-url="$SPREADSHEET_URL" \
  --buckets="$BUCKETS" \
  --user-project="$USER_PROJECT"

如需并行运行多个导入作业，请在 --buckets 参数中指定多个 Cloud Storage 存储分区。该脚本会将元数据拆分为较小的批次，并在存储分区中同时处理这些批次，从而缩短总注入时间。

**注意：** 将 Cloud Storage 存储分区列表格式化为不含空格的单个以逗号分隔字符串（例如， bucket-1,bucket-2,bucket-3）。为防止对 API 调用进行速率限制，请勿 指定超过 20 个存储分区。

您可以在本地执行路径的 logs/ 目录中查看执行日志。这些日志可帮助您审核传输过程，并识别跳过的条目或格式警告。

后续步骤

• 了解如何管理业务术语库。
• 了解如何将条目链接导出到 Google 表格。
• 了解如何 从 Google 表格导入术语表。
• 详细了解元数据管理。