此页面由 Cloud Translation API 翻译。

导入元数据

您可以导入 Dataplex Catalog 元数据条目及其各个方面 - 从第三方系统进入 Dataplex。

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

确定作业范围。

此外，了解 Dataplex 如何应用比较逻辑和条目和切面的同步模式。
创建一个或多个元数据导入文件，用于定义要导入的数据。
将元数据导入文件保存在 Cloud Storage 存储桶中。
运行元数据导入作业。

本页面中的步骤假定您熟悉 Dataplex Catalog 概念，包括条目组、条目类型和切面类型。如需了解详情，请参阅 Dataplex Catalog 概览。

准备工作

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

所需的角色

为了确保 Dataplex 服务账号拥有访问 Cloud Storage 存储桶所需的权限，请询问向 Dataplex 服务账号授予 Storage Object Viewer (roles/storage.objectViewer) IAM 角色以及对存储桶的 storage.buckets.get 权限。

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

Dataplex Entry Type User (roles/dataplex.entryTypeUser) 针对条目类型或定义了该条目类型的项目
Dataplex Aspect Type User (roles/dataplex.aspectTypeUser) 针对切面类型或定义了该切面类型的项目
创建元数据作业： <ph type="x-smartling-placeholder">
- Dataplex 条目组导入程序 (roles/dataplex.entryGroupImporter) 针对项目或资源
- Dataplex Entry Owner (roles/dataplex.entryOwner) 针对项目或资源
查看元数据作业： Dataplex Metadata Job Viewer (roles/dataplex.metadataJobViewer) 针对项目
创建、查看和取消元数据作业： Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) 针对项目

如需详细了解如何授予角色，请参阅管理访问权限。

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

创建 Google Cloud 资源

准备以下 Google Cloud 资源：

创建条目组。
创建切面类型。
创建条目类型。
创建 Cloud Storage 存储桶来存储您的元数据导入文件。

元数据作业的组成部分

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

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

作业范围

作业范围定义了条目组、条目类型以及可选的想要包含在元数据作业中的切面类型。导入时元数据，您可以修改属于范围。

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

条目组：指定要包含在作业中的单个条目组。该作业仅修改属于此条目组的条目。条目组和作业必须位于同一区域。
条目类型：指定要包含在作业中的一个或多个条目类型。工作只修改属于这些条目类型的条目。条目类型的位置必须与作业的位置匹配，或者条目类型必须为全局类型。
切面类型：可选。指定一个或多个要包含的切面类型工作中。如果为切面类型指定范围，则作业将修改只有属于这些切面类型的切面。切面类型的位置必须与作业的位置匹配，或者切面类型必须为全局类型。

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

同步模式

同步模式指定是执行完全更新，还是对元数据作业中的条目和切面进行增量更新。

FULL：支持条目。作业范围中的所有条目均为。

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

切面不支持完全同步。
INCREMENTAL：支持切面。仅修改了一个切面如果元数据导入文件在 updateMask 字段和 aspectKeys 字段。如需详细了解这些字段，请参阅本文档中的导入项的结构部分。

条目不支持增量同步。

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

元数据导入文件

元数据导入文件是您要创建的条目和方面的集合，您想要修改的文本。它定义了要为属于哪个字段的所有字段设置的值这些条目和方面。您需要先准备文件，然后再运行元数据作业。

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

您在文件中提供的条目将会完全取代条目。这意味着必须包含作业中所有条目的值，而不仅仅是您想添加或更新的对象获取项目中当前条目的列表使用 entries.list API 方法。

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

请按照以下部分中的指南创建元数据导入文件。

文件的结构

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

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

元数据导入文件的各个导入项之间有一个换行符，如下例所示：

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

导入项的结构

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

{
  "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": {
          "KEY": "VALUE"
        },
        "aspectSource": {
          "createTime": "ASPECT_CREATE_TIMESTAMP"
          "updateTime": "ASPECT_UPDATE_TIMESTAMP"
        }
      },
      # Additional aspect maps
    },
    "parentEntry": "PARENT_ENTRY",
    "fullyQualifiedName": "FULLY_QUALIFIED_NAME"
  },
  "updateMask": "UPDATE_MASK_FIELDS",
  "aspectKeys": [
    "ASPECT_KEY",
    # Additional aspect keys
  ],
}

替换以下内容：

ENTRY_NAME：条目的相对资源名称。格式为 projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID。
ENTRY_TYPE：用于创建此条目的条目类型，格式为 projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID。
entrySource：来自源系统由以下条目表示：
- RESOURCE：来源中资源的名称系统。
- SYSTEM：源系统的名称。
- PLATFORM：包含源系统的平台。
- DISPLAY_NAME：方便用户使用的显示名称。
- DESCRIPTION：条目的说明。
- ENTRY_CREATE_TIMESTAMP：条目发生的时间和在源系统中创建的
- ENTRY_UPDATE_TIMESTAMP：条目发生的时间更新。
aspects：附加到条目的切面。aspect 对象和其数据称为切面映射。
- ASPECT：附加到条目的切面。根据切面附加到条目的方式，使用以下某个选项格式：
  - 如果切面直接附加到条目，请提供相对资源其切面类型的名称，格式为 PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID。
  - 如果切面附加到条目的路径，请提供切面类型的路径，格式为 PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@PATH。
- KEY 和 VALUE：切面类型。相应内容必须编码为 UTF-8。该字段的大小上限为 120 KB。
- ASPECT_CREATE_TIMESTAMP：切面的创建时间源系统。
- ASPECT_UPDATE_TIMESTAMP：切面的更新时间源系统。
- PARENT_ENTRY：父条目的资源名称。
- FULLY_QUALIFIED_NAME：条目的名称，可由外部系统引用
UPDATE_MASK_FIELDS：要更新的字段，相对于 Entry 资源。用英文逗号分隔各个字段。

在 FULL 条目同步模式下，Dataplex 包含所有字段（包括切面）字段。

创建或重新创建条目时，系统会忽略 update_mask 字段。
ASPECT_KEY：要修改的切面。支持以下语法：
- ASPECT_TYPE_REFERENCE：与以下项的切面类型匹配：直接附加到条目的切面。
- ASPECT_TYPE_REFERENCE@PATH：匹配切面类型和指定路径。
- ASPECT_TYPE_REFERENCE@*：与切面类型匹配。
将 ASPECT_TYPE_REFERENCE 替换为对切面类型，格式为 PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID。

如果将此字段留空，则会被视为明确指定了。

在 FULL 条目同步模式下，Dataplex 会隐式添加该条目的所有必需方面

文件要求

元数据导入文件具有以下要求：

文件必须采用 JSON 行格式文件，即以换行符分隔的 JSON 文件。使用换行符 (0x0a) 来分隔每个导入项
文件必须使用 UTF-8 字符编码。
支持的文件扩展名为 .jsonl 和 .json。
文件大小必须小于 1 GiB。
您在文件中指定的条目和切面必须是导入作业的范围。
该文件必须上传到 Cloud Storage 存储桶。不保存文件放在名为 CLOUD_STORAGE_URI/deletions/ 的文件夹中。

比较逻辑

Dataplex 通过比较以及您在元数据导入文件中提供的时间戳和时间戳

概括来讲，Dataplex 会更新您项目中的值当元数据导入文件中至少有一项建议的更改将发生更改时触发作业运行时项目状态，而不会引入过时数据。必须在更新掩码字段或切面中引用建议的更改元数据导入文件中的键字段。

对于属于作业范围的每个条目，Dataplex 都会执行一项操作以下几项：

创建条目和附加切面。如果元数据导入文件包含项目中不存在的条目 Dataplex 创建条目和附加切面。
删除条目和附加的切面。如果您的但元数据导入文件不包含该条目， Dataplex 会从您的项目。
更新条目和附加切面。如果两个元素中都存在同一条目，元数据导入文件，在项目中使用 Dataplex 评估条目源时间戳和切面源时间戳，以确定要修改的值。然后， Dataplex 执行以下一项或多项操作：
- 重新创建该条目。如果条目源在元数据导入文件的时间比则 Dataplex 会在您的项目中重新创建该条目。
- 更新条目。如果元数据中的条目源更新时间戳导入文件的时间比您项目中的对应时间戳更新， Dataplex 会更新您项目中的条目。
- 创建切面。如果切面包含在元数据导入文件，但不包含在更新掩码字段中， Dataplex 创建切面。
- 删除切面。如果某个切面未包含在元数据导入文件，但它包含在更新掩码字段中， Dataplex 会删除切面。
- 更新切面。如果切面来源在元数据中更新时间戳导入文件的时间比您项目中的对应时间戳更新， Dataplex 会更新项目中的切面。如果 Dataplex 附加的条目是缺少条目源更新时间戳，或者条目源时间戳元数据导入文件中对应的时间戳比您项目中的对应时间戳更近。
  
  但是，如果元数据导入文件中至少有一个方面具有较旧的版本时间戳，则 Dataplex 不会对附加的条目进行任何更新。

创建元数据导入文件

在导入元数据之前，请为作业创建元数据导入文件。请按照以下步骤操作：

准备元数据导入文件，操作步骤如下本文档前面介绍的指南。
将文件上传到 Cloud Storage 存储桶。

您可以在同一个元数据作业中提供多个元数据导入文件。接收者提供多个文件，请将文件保存在同一个 Cloud Storage 中存储桶。运行该作业时，您需要指定存储桶，而不是特定文件。 Dataplex 会从 Google Cloud 控制台中（包括子文件夹中的文件）。

运行元数据导入作业

创建元数据导入文件后，使用 API。

REST

如需导入元数据，请使用 metadataJobs.create 方法。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_NUMBER：您的 Google Cloud 项目编号或项目 ID。
LOCATION_ID：Google Cloud 位置，例如 us-central1。
METADATA_JOB_ID：可选。元数据作业 ID。
CLOUD_STORAGE_URI：包含元数据导入文件的 Cloud Storage 存储桶或文件夹。有关请参阅元数据导入文件。
ENTRY_GROUP：符合以下条件的条目组的相对资源名称在作业范围内，格式为 projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID。请仅提供一个条目组。如需了解详情，请参阅作业范围。
ENTRY_TYPE：符合以下条件的条目类型的相对资源名称职位所涵盖的范围，格式为 projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID。如需了解详情，请参阅作业范围。
ASPECT_TYPE：可选。切面的相对资源名称作业范围内的类型，格式为 projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID。如需了解详情，请参阅作业范围。
LOG_LEVEL：要捕获的日志级别，例如 INFO 或 DEBUG。如需了解详情，请参阅查看作业日志并排查问题。

HTTP 方法和网址：

POST https://dataplex.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

请求 JSON 正文：

{
  "type": IMPORT,
  "import_spec": {
    "source_storage_uri": gs://CLOUD_STORAGE_URI/,
    "scope": {
      "entryGroups": [
        ENTRY_GROUP
      ],
      "entry_types": [
        ENTRY_TYPE
      ],
      "aspect_types": [
        ASPECT_TYPE
      ]
    },
    "entry_sync_mode": FULL,
    "aspect_sync_mode": INCREMENTAL,
    "log_level": LOG_LEVEL
  }
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dataplex.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dataplex.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID" | Select-Object -Expand Content

该响应可识别长时间运行的操作。

获取有关元数据作业的详细信息

如需获取有关元数据作业的信息，例如作业的状态和修改的条目数，请按以下步骤操作。如需详细了解如何对失败的作业进行问题排查，请参阅本文档的查看作业日志和问题排查部分。

REST

如需获取有关元数据作业的信息，请使用 metadataJobs.get 方法。

获取元数据作业列表

您可以获取最新元数据作业的列表。有定期从系统中删除。

REST

如需获取最新元数据作业的列表，请使用 metadataJobs.list 方法。

取消元数据作业

您可以取消不想运行的元数据作业。

REST

要取消元数据作业，请使用 metadataJobs.cancel 方法。

查看作业日志并排查问题

使用 Cloud Logging 查看元数据作业的日志。如需了解详情，请参阅监控 Dataplex 日志。

您需要在创建元数据作业时配置日志级别。以下日志级别：

INFO：提供整个作业级别的日志。包含关于以下内容的汇总日志：但不指定哪个导入项出现错误。
DEBUG：提供每个导入项的详细日志。使用调试级日志记录排查特定导入项的问题。例如，使用调试级日志记录，以确定作业中缺少的资源范围、条目或切面不符合相关条目类型，或切面类型或者元数据导入文件的其他错误配置。

注意：根据元数据作业的大小以及调试级日志记录可能会产生额外费用。有关相关信息，请参阅 Google Cloud Observability 价格。

验证错误

Dataplex 会根据当前的元数据。如果存在验证问题，则作业状态返回以下状态之一：

FAILED：当元数据导入文件出现错误时，会发生以下情况。 Dataplex 不会导入任何元数据，并且作业会失败。示例元数据导入文件中的错误包括： <ph type="x-smartling-placeholder">
- 无法将文件中的内容解析为有效的导入内容
- 文件中的条目或切面属于某个条目组、条目类型或不属于作业范围的切面类型
- 在该作业中多次指定了同一个条目名称
- 在切面映射或切面键中指定的切面类型不使用 PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@OPTIONAL_PATH
SUCCEEDED_WITH_ERRORS：当元数据导入文件可以已成功解析，但是在文件中导入项会导致导致项目处于不一致状态Dataplex 忽略但会从文件导入其余的元数据。

使用作业日志排查错误。

导入元数据

准备工作

所需的角色

创建 Google Cloud 资源

元数据作业的组成部分

作业范围

同步模式

元数据导入文件

文件的结构

导入项的结构

文件要求

比较逻辑

创建元数据导入文件

运行元数据导入作业

REST

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

获取有关元数据作业的详细信息

REST

获取元数据作业列表

REST

取消元数据作业

REST

查看作业日志并排查问题

验证错误

后续步骤