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

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

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

  1. 从 Data Catalog 中导出术语库、类别和术语。
  2. 将术语库、类别和术语导入 Dataplex Universal Catalog。
  3. 从 Data Catalog 导出术语之间的链接。
  4. 将术语之间的链接导入 Dataplex Universal Catalog。
  5. 从 Data Catalog 导出术语与列之间的链接。
  6. 将术语与列之间的链接导入 Dataplex Universal Catalog。

所需的角色

如需从 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 中导出术语库、类别和术语

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

  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 \
--user-project="PROJECT_ID" \
--url="DATA_CATALOG_GLOSSARY_URL" \
--export-mode=glossary_only

    替换以下内容：

    • PROJECT_ID：包含术语库的项目的 ID。
    • DATA_CATALOG_GLOSSARY_URL：控制台中 Data Catalog 业务术语库的网址。

    该脚本会创建一个 JSON 文件，其格式与用于元数据导入作业的元数据导入文件相同。术语库、类别和术语的名称采用以下格式：

    • 术语库：projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID
    • 术语：projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM_ID
    • 类别：projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID

    其中，GLOSSARY_ID、CATEGORY_ID、TERM_ID、PROJECT_NUMBER 和 LOCATION_ID 与 Data Catalog 术语库中的值相同。

导入术语库、类别和术语

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

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

  2. 为 Dataplex Universal 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_NUMBER/locations/global/metadataJobs?metadata_job_id=JOB_ID -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_NUMBER/locations/global/glossaries/GLOSSARY_ID"]
    }
}
}
EOF
)"

    替换以下内容：

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

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

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

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

从 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 \
--user-project=PROJECT_ID \
--url="DATA_CATALOG_GLOSSARY_URL" \
--export-mode=entry_links_only \
--entrylinktype="related,synonym"

    该脚本会创建一个 JSON 文件，其中包含术语之间的同义词和相关链接。导出的文件位于 dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import 下的 Exported_Files 文件夹中。该文件的名称为 entrylinks_relatedsynonymGLOSSARY_ID.json。

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

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

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

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

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

    # Import CURL Command
gcurl https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs?metadata_job_id=JOB_ID -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": [PROJECT_IDS]
    }
}
}
EOF
)"

    替换以下内容：

    • GLOSSARY_PROJECT_ID：包含术语库的项目的 ID
    • PROJECT_IDS：如果术语在不同项目中的术语库之间存在链接，请以 "projects/PROJECT_ID1", "projects/PROJECT_ID2" 格式提供项目的 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。

导出术语与列之间的链接

导出并导入术语库和术语之间的链接后，继续导入术语与列之间的链接。在以下命令中，链接类型设置为定义，以导出术语与列之间的链接。

## Clone the repository and navigate to the directory
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);

## Run the export code
python3 bg_import/business_glossary_export_v2.py \
 --user-project="PROJECT_ID" \
 --url="DATA_CATALOG_GLOSSARY_URL" \
 --export-mode=entry_links_only \
 --entrylinktype="definition"

导入术语与列之间的链接

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

  1. 按照第 2 步中的说明，将上一步中导出的每个文件上传到 Cloud Storage 存储桶。

  2. 针对 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/ENTRY_GROUP_PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID
{
   "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":[
            PROJECT_IDS
         ]
      }
   }
}
EOF
)"

后续步骤