手动转换到 Dataplex Universal Catalog 中的业务术语库

本文档提供了相关说明，可帮助您从支持 Data Catalog 元数据的业务术语库预览版迁移到支持 Dataplex Universal Catalog 元数据的业务术语库正式版。转换流程包括从 Data Catalog 导出术语库、类别、术语和链接，然后将它们导入 Dataplex Universal Catalog。

如需手动转换到 Dataplex Universal Catalog 中的业务术语库，请按照以下步骤操作：

从 Data Catalog 导出术语库和条目链接。
将术语库、类别和术语导入 Dataplex Universal Catalog。
将术语之间的链接导入 Dataplex Universal Catalog。
将术语与列之间的链接导入 Dataplex Universal Catalog。

准备工作

如需启用从 Data Catalog 中的术语库导出的功能，请使用此表单进行注册。

安装 gcloud 或 Python 软件包。

所需的角色

如需从 Data Catalog 导出术语库，您需要拥有该术语库所在项目的 roles/datacatalog.glossaryOwner 角色。查看此角色所需的权限。

如需获得将业务术语库导入 Dataplex Universal Catalog 所需的权限，请让您的管理员为您授予项目的 Dataplex Administrator (roles/dataplex.admin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色可提供将业务术语库导入 Dataplex Universal Catalog 所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

将业务术语库导入 Dataplex Universal Catalog 需要以下权限：

针对术语库资源的 dataplex.glossaries.import
针对在 entry_groups 字段中提供的 Dataplex Universal Catalog 条目组以及链接到术语库术语的 Data Catalog 条目所在条目组的 dataplex.entryGroups.import
针对在 entry_groups 字段中提供的 Dataplex Universal Catalog 条目组以及链接到术语库术语的 Data Catalog 条目所在条目组的 dataplex.entryGroups.useSynonymEntryLink
针对在 entry_groups 字段中提供的 Dataplex Universal Catalog 条目组以及链接到术语库术语的 Data Catalog 条目所在条目组的 dataplex.entryGroups.useRelatedEntryLink
针对在 referenced_entry_scopes 字段中提供的所有项目的 dataplex.entryLinks.reference

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

从 Data Catalog 中导出术语库、类别和术语

您一次只能导出一个术语库。

克隆 dataplex-labs 仓库，然后将目录更改为 business-glossary-import 子目录：

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

获取访问令牌：

export GCLOUD_ACCESS_TOKEN=$(gcloud auth print-access-token)

运行导出脚本：
```
python3 bg_import/business_glossary_export_v2.py \
--user-project="PROJECT_ID" \
--url="DATA_CATALOG_GLOSSARY_URL"
```
替换以下内容：
- PROJECT_ID：包含术语库的项目的 ID。
- DATA_CATALOG_GLOSSARY_URL： Google Cloud 控制台中 Data Catalog 业务术语库的网址。
该脚本会创建一个 JSON 文件，其格式与用于元数据导入作业的元数据导入文件相同。术语库、类别和术语的名称采用以下格式：
- 术语库：projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/{PROJECT_ID{"</var>"}}/locations/LOCATION_ID/glossaries/GLOSSARY_ID
- 术语：projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM_ID
- 类别：projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID
其中，GLOSSARY_ID、CATEGORY_ID、TERM_ID、PROJECT_ID 和 LOCATION_ID 与 Data Catalog 术语库中的值相同。

结果

以下列表介绍了有关结果的注意事项：

术语库及其类别和术语会导出到全球位置，这样一来，术语就可以链接到任何区域中的条目。
导出的文件位于 dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import 下的 Exported_Files 文件夹中。该文件的名称为 glossary_GLOSSARY_ID.json。
导出命令会自动在 Dataplex Universal Catalog 中创建具有相同 GLOSSARY_ID 和 PROJECT_ID 的术语库（位于全球位置）。
该脚本会创建一个 JSON 文件，其中包含术语之间的同义词和相关链接。导出的文件位于 dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import 中的 Exported_Files 文件夹中。该文件的名称为 entrylinks_related_synonym_GLOSSARY_ID.json。
导出的链接位于 dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import 下的 Exported_Files 文件夹中。
术语库中的术语可能会链接到多个条目组中的多个条目。导出术语与列之间的关联会为每个 entryGroup 创建一个文件。文件名的格式为：entrylinks_definition_export_GLOSSARY_ID_ENTRY_PROJECT_ID_ENTRY_LOCATION_ID_ENTRY_GROUP_ID.json。
导出脚本运行后，系统会显示导入术语库、类别和术语所需的术语库 ID。

导入术语库、类别和术语

您需要导入在上一步中导出的 Dataplex Universal Catalog 术语库、类别和术语。本部分介绍了如何使用元数据作业 API 进行导入。

创建 Cloud Storage 存储桶，然后将文件上传到该存储桶。
为 Dataplex Universal Catalog 服务账号授予对 Cloud Storage 存储桶的读取权限。

运行元数据导入作业以导入术语表。

# Set GCURL alias
alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

# Import CURL Command
gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs\?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -d "$(cat<<EOF
{
"type":"IMPORT",
"import_spec":{
    "log_level": "DEBUG",
    "source_storage_uri": "gs://STORAGE_BUCKET/",
    "entry_sync_mode": "FULL",
    "aspect_sync_mode": "INCREMENTAL",
    "scope": {
      "glossaries": ["projects/PROJECT_ID/locations/global/glossaries/GLOSSARY_ID"]
    }
}
}
EOF
)"

替换以下内容：

JOB_ID：（可选）元数据导入作业 ID，您可以使用该 ID 跟踪作业的状态。如果您未提供 ID，gcurl 命令会生成一个唯一 ID。
STORAGE_BUCKET：包含导出的术语库文件的 Cloud Storage 存储桶或文件夹的 URI。
PROJECT_ID：包含术语库的项目的编号。

可选：如需跟踪元数据导入作业的状态，请使用 metadataJobs.get 方法：
```
gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs/JOB_ID
```
如果您在元数据导入作业中遇到任何错误，这些错误都会显示在日志中。

将术语之间的链接导入 Dataplex Universal Catalog

您需要导入在上一步中导出的术语之间的链接。本部分介绍了如何使用元数据作业 API 进行导入。

创建一个新的 Cloud Storage 存储桶，然后将上一步中导出的条目链接文件上传到该存储桶中。
为 Dataplex Universal Catalog 服务账号授予对 Cloud Storage 存储桶的读取权限。

运行元数据导入作业以导入条目链接：

# Import CURL Command
gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -d "$(cat<<EOF
{
"type": "IMPORT",
"import_spec": {
  "log_level": "DEBUG",
  "source_storage_uri": "gs://STORAGE_BUCKET/",
  "entry_sync_mode": "FULL",
  "aspect_sync_mode": "INCREMENTAL",
  "scope": {
    "entry_groups": ["projects/GLOSSARY_PROJECT_ID/locations/global/entryGroups/@dataplex"],
    "entry_link_types": [
      "projects/dataplex-types/locations/global/entryLinkTypes/synonym",
      "projects/dataplex-types/locations/global/entryLinkTypes/related"
    ],
    "referenced_entry_scopes": ["projects/GLOSSARY_PROJECT_ID","projects/LINKED_GLOSSARY_PROJECT_ID_1","projects/LINKED_GLOSSARY_PROJECT_ID_2"]
  }
}
}
EOF
)"

替换以下内容：

GLOSSARY_PROJECT_ID：包含术语库的项目的 ID
可选：LINKED_GLOSSARY_PROJECT_ID_1：如果术语在不同项目中的术语库之间存在链接，请提供相应项目的 ID
可选：LINKED_GLOSSARY_PROJECT_ID_2：如果术语在不同项目中的术语库之间存在链接，请提供相应项目的 ID

请注意以下几点：

entry_groups 对象包含在其中创建条目链接的条目组。这是与术语库位于同一项目和位置的 @dataplex 系统条目组。
借助 entry_link_types 对象，您可以导入同义词和/或相关字词：
- 同义词：projects/dataplex-types/locations/global/entryLinkTypes/synonym
- 相关字词：projects/dataplex-types/locations/global/entryLinkTypes/related
referenced_entry_scopes 对象包含链接不同术语库中术语的条目链接的项目 ID。

导入术语与列之间的链接

您需要导入在上一步中导出的术语与列之间的链接。本部分介绍了如何使用元数据作业 API 进行导入。

将上一步中导出的每个文件上传到 Cloud Storage 存储桶。
针对 Cloud Storage 存储桶中上传的每个文件运行单独的导入命令。每个文件对应于一个唯一的条目组，其中包含该条目组的术语与列之间的链接。

gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID/metadataJobs?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -d "$(cat<<EOF
{
"type": "IMPORT",
"import_spec": {
    "log_level": "DEBUG",
    "source_storage_uri": "gs://STORAGE_BUCKET/",
    "entry_sync_mode": "FULL",
    "aspect_sync_mode": "INCREMENTAL",
    "scope": {
        "entry_groups": ["projects/ENTRY_GROUP_PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID/entryGroups/ENTRY_GROUP_ID"],
        "entry_link_types": ["projects/dataplex-types/locations/global/entryLinkTypes/definition"],
        "referenced_entry_scopes": ["projects/ENTRY_GROUP_PROJECT_ID", "projects/GLOSSARY_PROJECT_ID"]
    }
}
}
EOF
)"