使用自定义流水线导入元数据

本文档介绍了如何使用元数据导入 API 方法和您自己的流水线，将元数据从第三方系统导入 Dataplex Universal Catalog。Dataplex Universal Catalog 元数据由条目及其切面组成。

如果您想使用 Google Cloud管理的编排流水线来提取和导入元数据，建议使用托管式连接流水线。借助托管式连接流水线，您可以自带连接器，该连接器会提取元数据，并以可用作元数据导入 API 方法（元数据导入文件）的输入的格式生成输出。然后，您可以使用 Workflows 来编排流水线任务。

您可以运行以下类型的元数据导入作业：

  • 完全同步条目，并以增量方式导入条目的切面。支持自定义条目。
  • 仅增量导入切面。支持属于自定义条目和系统条目的切面。对于自定义条目，您可以修改可选切面和必需的切面。对于系统条目，您可以修改可选切面。

简要步骤

如需使用元数据导入 API 导入元数据，请按照以下简要步骤操作：

  1. 确定作业范围。

    此外，还需要了解 Dataplex Universal Catalog 如何为条目和切面应用比较逻辑和同步模式。

  2. 创建一个或多个元数据导入文件，以定义要导入的数据。

  3. 将元数据导入文件保存在 Cloud Storage 存储桶中。

  4. 运行元数据导入作业。

本页面中的步骤假设您熟悉 Dataplex Universal Catalog 元数据概念，包括条目组、条目类型和切面类型。如需了解详情，请参阅 Dataplex Universal Catalog 中的元数据管理简介。

准备工作

在导入元数据之前，请完成本部分中的任务。

所需的角色

如需确保 Dataplex Universal Catalog 服务账号拥有访问 Cloud Storage 存储桶所需的权限，请让您的管理员为 Dataplex Universal Catalog 服务账号授予该存储桶的 Storage Object Viewer (roles/storage.objectViewer) IAM 角色和 storage.buckets.get 权限。

如需获得管理元数据导入作业所需的权限，请让您的管理员为您授予以下 IAM 角色：

  • 在完整条目同步元数据作业中修改条目及其切面：
  • 在仅切面的元数据作业中修改必需的切面：
  • 在仅切面的元数据作业中修改可选切面：针对切面类型或在其中定义切面类型的项目的 Dataplex Aspect Type User (roles/dataplex.aspectTypeUser)。请注意，在仅切面的元数据的作业中修改可选切面时，您无需拥有关联的条目类型的权限。
  • 创建元数据导入作业：
  • 查看元数据作业：针对项目的 Dataplex Metadata Job Viewer (roles/dataplex.metadataJobViewer)
  • 创建、查看和取消元数据作业：针对项目的 Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner)

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

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

创建 Google Cloud 资源

准备以下 Google Cloud 资源：

  1. 为要导入的条目创建条目组。
  2. 为要导入的切面创建切面类型。
  3. 为要导入的条目创建条目类型。
  4. 如果您要运行仅切面的元数据作业，请为要导入的切面创建条目。
  5. 创建一个 Cloud Storage 存储桶以存储元数据导入文件。

元数据导入作业的组成部分

导入元数据时，请考虑元数据作业的以下组成部分：

  • 作业范围：要包含在作业中的条目组、条目类型和切面类型。
  • 同步模式：如何更新作业中的条目和切面。
  • 元数据导入文件：用于定义要为作业中的条目和切面设置的值的文件。您可以在同一元数据作业中提供多个元数据导入文件。您将文件保存在 Cloud Storage 中。
  • 比较逻辑：Dataplex Universal Catalog 如何确定要修改哪些条目和切面。

作业范围

作业范围用于定义您要包含在元数据导入作业中的条目组、条目类型和切面类型。导入元数据时，您需要修改属于作业范围内的资源的条目和切面。

如需定义作业范围，请遵循以下准则：

  • 条目组：指定要包含在作业中的一个或多个条目组。作业仅会修改属于这些条目组的条目和切面。条目组和作业必须位于同一区域。

  • 条目类型：指定要在作业中包含的一个或多个条目类型。作业仅会修改属于这些条目类型的条目和切面。条目类型的位置必须与作业位置匹配，或者条目类型必须是全球性的。

  • 切面类型：指定要在作业中包含的一个或多个切面类型。作业仅会修改属于这些切面类型的切面。切面类型的位置必须与作业位置匹配，或者切面类型必须是全球性的。

作业范围必须包含您在元数据导入文件中指定的所有条目类型和切面类型。

您可以在创建元数据作业时指定作业范围。

同步模式

同步模式用于指定如何更新元数据导入作业中的条目和切面。您需要为条目和切面都提供同步模式。根据您要导入的资源，系统支持以下同步模式组合。

目标 条目同步模式 切面同步模式 结果
导入条目及其切面 FULL INCREMENTAL

作业范围内的所有条目都会被修改。

如果 Dataplex Universal Catalog 中存在某个条目，但该条目未包含在元数据导入文件中，则在您运行元数据作业时，该条目会被删除。

只有当元数据导入文件在 updateMask 字段和 aspectKeys 字段中包含对相应切面的引用时，才会修改该切面。请参阅导入项的结构。
仅导入切面 NONE INCREMENTAL

如果切面属于作业的范围，并且元数据导入文件在 aspectKeys 字段中包含对切面的引用，则会修改这些切面。请参阅导入项的结构。

属于作业范围内的条目的其他元数据不会被修改。

您可以在创建元数据作业时指定同步模式。

元数据导入文件

元数据导入文件是您要修改的条目和切面的集合。它定义了要为属于这些条目和切面的所有字段设置的值。您需要在运行元数据导入作业之前准备好该文件。

请遵循以下一般准则：

  • 您可以在同一元数据作业中提供多个元数据导入文件。

  • 运行完整条目同步元数据作业时，您在文件中提供的条目会完全替换作业范围内的所有资源的所有现有条目。这意味着您必须为作业中的所有条目都提供值，而不仅仅是您要添加或更新的值。如需获取项目中的当前条目列表以用作起点，请使用 entries.list API 方法。

  • 您必须在元数据作业中提供元数据导入文件。如果您想删除作业范围内的条目的所有现有数据，请提供一个空的元数据导入文件。

  • 您在文件中包含的所有条目和切面都必须属于您在作业范围内定义的条目组、条目类型和切面类型。

请按照以下各部分中的详细准则创建元数据导入文件。

文件的结构

元数据导入文件中的每一行都包含一个与一个导入项对应的 JSON 对象。导入项是一个对象，用于描述要针对条目及其附加切面修改的值。

您可以在单个元数据导入文件中提供多个导入项。不过，请勿在元数据作业中多次提供相同的导入项。使用换行符 (0x0a) 分隔每个导入项。

每个导入项之间都有换行符的元数据导入文件如以下示例所示：

{ "entry": { "name": "entry 1", #Information about entry 1 }
{ "entry": { "name": "entry 2", #Information about entry 2 }

导入项的结构

元数据导入文件中的每个导入项都可以包含以下字段（请参阅 ImportItem）。以下示例的格式设置中包含换行符，以便于阅读，但保存文件时，请仅在每个导入项后添加换行符。请勿在单个导入项的字段之间添加换行符。

{
  "entry": {
    "name": "ENTRY_NAME",
    "entryType": "ENTRY_TYPE",
    "entrySource": {
      "resource": "RESOURCE",
      "system": "SYSTEM",
      "platform": "PLATFORM",
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "createTime": "ENTRY_CREATE_TIMESTAMP",
      "updateTime": "ENTRY_UPDATE_TIMESTAMP"
    },
    "aspects": {
      "ASPECT": {
        "data": {
          "