本文档介绍了如何导入 Dataplex Catalog 元数据 使用元数据导入 API 从第三方系统传输到 Dataplex 方法和您自己的流水线。Dataplex Catalog 元数据 由条目及其各个方面组成。
如果您想改用 Google Cloud 代管式编排流水线 来提取和导入元数据，我们建议您使用 代管式连接流水线。 借助托管式连接管道，您可以使用自己的连接器提取元数据，并以元数据导入 API 方法（元数据导入文件）可用作输入的格式生成输出。然后，使用 用于编排流水线任务的 Workflows。
简要步骤
如需使用元数据导入 API 导入元数据，请按照以下简要步骤操作：
确定作业范围。
此外，了解 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) 角色 -
创建元数据作业：
-
针对项目或资源的 Dataplex Entry Group Importer (
roles/dataplex.entryGroupImporter) -
Dataplex Entry Owner (
roles/dataplex.entryOwner) 针对项目或资源
-
针对项目或资源的 Dataplex Entry Group Importer (
-
查看元数据作业：
项目的 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.listAPI 方法。您必须在元数据作业中提供元数据导入文件。如果您想 删除作业范围内条目的所有现有数据， 提供一个空的元数据导入文件。
您在文件中添加的所有条目和方面都必须属于您在作业范围内定义的条目组、条目类型和方面类型。
使用下面几部分中的详细准则来创建元数据 导入文件。
文件的结构
元数据导入文件中的每一行都包含一个 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": {
"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。
data必须输入字典，即使该字典为空。ASPECT_CREATE_TIMESTAMP：切面的创建时间 源系统。
ASPECT_UPDATE_TIMESTAMP：相应方面在源系统中更新的时间。
PARENT_ENTRY：父条目的资源名称。
FULLY_QUALIFIED_NAME：条目的名称，可 由外部系统引用请参阅完全限定名称。
UPDATE_MASK_FIELDS：要更新的字段，以相对于
Entry资源的路径表示。每个字段之间用英文逗号分隔。在
FULL条目同步模式下，Dataplex 会包含可修改的条目的所有字段（包括方面）的路径。创建或重新创建条目时，系统会忽略
updateMask字段。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。通过 元数据作业中所有数据的总大小上限为 3 GB。这包括与作业关联的所有文件和元数据。
- 您在文件中指定的条目和切面必须是 元数据作业的范围。
- 该文件必须上传到 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 会从以下文件中保存的所有文件导入元数据： （包括子文件夹中的文件）。
运行元数据导入作业
创建元数据导入文件后，使用 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
}
}
如需发送您的请求，请展开以下选项之一：
该响应用于标识长时间运行的操作。
获取元数据作业的详细信息
如需获取元数据作业的信息（例如作业的状态和修改的条目数量），请按以下步骤操作。如需详细了解如何排查作业失败问题，请参阅本文档的查看作业日志和排查问题部分。
REST
如需获取有关元数据作业的信息，请使用
metadataJobs.get 方法。
获取元数据作业列表
您可以获取最新元数据作业的列表。包含 定期从系统中删除。
REST
如需获取最新元数据作业的列表，请使用 metadataJobs.list 方法。
取消元数据作业
您可以取消不想运行的元数据作业。
REST
如需取消元数据作业，请使用 metadataJobs.cancel 方法。
查看作业日志和排查问题
使用 Cloud Logging 查看元数据作业的日志。如需了解详情，请参阅监控 Dataplex 日志。
您可以在创建元数据作业时配置日志级别。以下日志 级别：
INFO：在整个作业级别提供日志。包含有关导入项的汇总日志，但未指定哪个导入项存在错误。DEBUG：提供每个导入项的详细日志。使用调试级日志记录来排查特定导入项的问题。例如，使用调试级日志记录来确定作业范围中缺少的资源、不符合关联条目类型或方面类型的条目或方面，或元数据导入文件的其他错误配置。
验证错误
Dataplex 会根据当前的 元数据。如果存在验证问题，作业状态可能会返回以下某种状态：
FAILED：当元数据导入文件出现错误时，会发生以下情况。 Dataplex 不会导入任何元数据，并且作业会失败。元数据导入文件中的错误示例包括：- 文件中的某个项无法解析为有效的导入项
- 文件中的条目或方面属于不属于作业范围的条目组、条目类型或方面类型
- 在该作业中多次指定了同一个条目名称
- 在方面映射或方面键中指定的方面类型不使用 PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@OPTIONAL_PATH 格式
SUCCEEDED_WITH_ERRORS：当元数据导入文件可以 成功解析，但是在文件中导入项会导致 导致项目处于不一致状态Dataplex 忽略 但会从文件导入其余的元数据。
使用作业日志排查错误。