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

本文档介绍了如何从支持 Data Catalog 元数据的业务术语库预览版迁移到支持 Knowledge Catalog（以前称为 Dataplex Universal Catalog）元数据的业务术语库正式版。转换过程包括从 Data Catalog 导出术语库、类别、术语和链接，然后将它们导入 Knowledge Catalog。

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

  1. 从 Data Catalog 导出术语库和条目链接。
  2. 将术语库、类别和术语导入 Knowledge Catalog。
  3. 将术语之间的链接导入 Knowledge Catalog。
  4. 将术语与列之间的链接导入 Knowledge Catalog。

准备工作

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

安装 gcloud 或 Python 软件包。

所需的角色

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

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

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

所需权限

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

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

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

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

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

  1. 克隆 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

  2. 获取访问令牌：

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

  3. 运行导出脚本：

    python3 bg_import/business_glossary_export_v2.py \
--project="PROJECT_ID" \
--url="DATA_CATALOG_GLOSSARY_URL"

    替换以下内容：

    • PROJECT_ID：包含术语库的项目的 ID。此项目还用于结算和配额。
    • DATA_CATALOG_GLOSSARY_URL：Data Catalog 业务术语库在 控制台中显示的全网址。Google Cloud

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

    该脚本会创建一个 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。

  • 导出命令会自动在 Knowledge 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。

导入术语库、类别和术语

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

  1. 创建 Cloud Storage 存储桶，然后 将文件上传到该存储桶。

  2. 为 Knowledge Catalog 服务帐号授予对 Cloud Storage 存储桶的读取权限。

  3. 运行元数据导入作业 以导入术语库。

    # 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：包含术语库的项目的编号。

  4. 可选：如需跟踪元数据导入作业的状态，请使用 metadataJobs.get 方法：

    gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs/JOB_ID

    如果您在元数据导入作业中遇到任何错误，这些错误都会显示在日志中。

将术语之间的链接导入 Knowledge Catalog

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

  1. 创建一个新的 Cloud Storage 存储桶，然后将上一步中导出的条目链接文件上传到该存储桶中。

  2. 为 Knowledge Catalog 服务帐号授予对 Cloud Storage 存储桶的读取权限。

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

    # 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进行导入。

  1. 将上一步中导出的每个文件上传到 Cloud Storage 存储桶。

  2. 针对 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
)"

后续步骤