本文档介绍了如何使用 REST API 为 Knowledge Catalog（以前称为 Dataplex Universal Catalog）中的条目组提交批量元数据更改请求。
如果您没有对条目组的直接写入权限，则可以将最多 250 个针对条目和条目链接的创建、更新和删除操作分组到单个更改请求中，以供审核和批准。
准备工作
如需提交批量元数据更改请求，请确保您已启用所需的 API，并且对目标条目组拥有必要的 Identity and Access Management (IAM) 角色和权限。
启用 Dataplex API（如果尚未启用）。
启用 API 所需的角色
如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。
所需的角色
如需获得为条目群组请求批量元数据更改所需的权限，请让管理员向您授予目标条目群组的以下 IAM 角色：
-
提交批量元数据更改请求：Dataplex Catalog Viewer (
roles/dataplex.catalogViewer)
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
如需详细了解角色和权限，请参阅 Knowledge Catalog IAM 角色。
创建批量元数据更改请求
当您提交批量更改请求时，Knowledge Catalog 会检查请求语法，并验证任何引用的条目类型、切面类型、条目链接类型和父条目是否存在。请求获得批准后，Knowledge Catalog 会检查目标条目和条目链接是否存在，例如，在创建现有资源时返回 ALREADY_EXISTS 错误，或在更新或删除缺失资源时返回 NOT_FOUND 错误。
当审批人批准批量更改请求时，Knowledge Catalog 会自动按以下依赖顺序应用操作：
- 删除条目链接。
- 删除条目。
- 创建和更新条目。
- 创建和更新条目链接。
批量更改请求不提供事务一致性或自动回滚。获得批准后，Knowledge Catalog 会单独评估并应用每项操作。
构建批处理时，请注意以下引用规则：
- 请勿引用在同一批次中删除的条目：您无法创建或更新引用在同一批次中删除的条目的条目链接，也无法将
parentEntry设置为在同一批次中删除的条目。 - 在子条目之前列出父条目：如果新条目引用同一批次中的另一个条目作为其
parentEntry，请在创建子条目的请求之前列出创建父条目的请求。创建条目或条目链接时，parent条目组字段是可选的。如果您省略parent，Knowledge Catalog 会使用changePayload.name中的条目组。如果您添加了parent，则它必须与changePayload.name匹配。
如需提交基本批量元数据更改请求，请使用 entryGroups.requestBatchMetadataChange 方法：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
"changePayload": {
"name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
"changes": [
{
"createEntryRequest": {
"parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
"entryId": "ENTRY_ID",
"entry": {
"entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID"
}
}
}
]
},
"justification": "JUSTIFICATION"
}' \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestBatchMetadataChange"
替换以下内容：
PROJECT_ID：包含条目组的 Google Cloud项目的 ID。LOCATION：条目组的位置，例如us-central1。ENTRY_GROUP_ID：目标条目群组的 ID。ENTRY_ID：要创建的新条目的 ID。ENTRY_TYPE_ID：新条目的条目类型 ID。JUSTIFICATION：需要元数据更改请求的原因，最多 1,024 个字符。
该服务会返回一个响应，其中包含所创建的变更请求的资源名称：
{
"changeRequest": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32"
}
验证创建的批量更改请求
如需检查创建的变更请求，请使用 changeRequests.get 方法：
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID"
替换以下内容：
PROJECT_ID：您的Google Cloud 项目的 ID。LOCATION：资源所在的区域，例如us-central1。CHANGE_REQUEST_ID：请求的唯一 ID。
该服务会返回一个包含批量载荷的 ChangeRequest 资源：
用户提交的批量更改请求的示例响应
{ "name": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32", "uid": "eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32", "createTime": "2026-09-14T09:06:40.352156739Z", "updateTime": "2026-09-14T09:06:41.714939166Z", "justification": "Requesting creation of a new entry", "author": "requester@example.com", "state": "NEW", "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group", "etag": "0YSwO12PxwypRJj6kqM3CTZ9BYk4wk3yasxdiMDE3MU", "changeType": "BATCH_CHANGE_METADATA", "batchChangeMetadataRequest": { "name": "projects/my-project/locations/us-central1/entryGroups/my-entry-group", "changes": [ { "createEntryRequest": { "parent": "projects/my-project/locations/us-central1/entryGroups/my-entry-group", "entryId": "new-entry-id", "entry": { "entryType": "projects/my-project/locations/us-central1/entryTypes/my-entry-type" } } } ] } }
如果富化代理运行自动创建了批量更改请求，则 author 字段包含富化代理服务账号，batchChangeMetadataRequest.description.job.name 字段包含富化运行资源名称。
创建多资源批量更改请求
如需在单个条目组中提议对多个资源进行更改，请使用 entryGroups.requestBatchMetadataChange 方法。例如，您可以使用此方法创建第一个条目，创建附加了切面的第二个条目，然后创建连接这两个条目的定向条目链接。
如需创建多资源批量更改请求，请发送以下 POST 请求：
用于创建多资源批量变更请求的示例请求
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID", "changePayload": { "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID", "changes": [ { "createEntryRequest": { "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID", "entryId": "FIRST_ENTRY_ID", "entry": { "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID" } } }, { "createEntryRequest": { "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID", "entryId": "SECOND_ENTRY_ID", "entry": { "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID", "aspects": { "PROJECT_ID.LOCATION.ASPECT_TYPE_ID": { "data": { "ASPECT_FIELD_NAME": "ASPECT_FIELD_VALUE" } } } } } }, { "createEntryLinkRequest": { "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID", "entryLinkId": "ENTRY_LINK_ID", "entryLink": { "entryLinkType": "projects/PROJECT_ID/locations/LOCATION/entryLinkTypes/ENTRY_LINK_TYPE_ID", "entryReferences": [ { "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/FIRST_ENTRY_ID", "type": "SOURCE" }, { "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/SECOND_ENTRY_ID", "type": "TARGET" } ] } } } ] }, "justification": "JUSTIFICATION" }' \ "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestBatchMetadataChange"
替换以下内容：
PROJECT_ID：包含条目组的Google Cloud 项目的 ID。LOCATION：条目组的位置，例如us-central1。ENTRY_GROUP_ID：目标条目群组的 ID。FIRST_ENTRY_ID：第一个自定义条目的 ID，用作条目链接中的SOURCE。SECOND_ENTRY_ID：附加了切面的第二个自定义条目的 ID，用作条目链接中的TARGET。ENTRY_TYPE_ID：新条目的条目类型 ID。ASPECT_TYPE_ID：附加到第二个条目的切面类型的 ID。ASPECT_FIELD_NAME：切面模板中字段的名称。ASPECT_FIELD_VALUE：切面字段的值。ENTRY_LINK_ID：连接两个条目的条目链接的 ID。ENTRY_LINK_TYPE_ID：条目链接类型的 ID，例如my-entry-link-type。JUSTIFICATION：说明为何需要这些元数据更改。
该服务会返回一个响应，其中包含所创建的变更请求的资源名称：
{
"changeRequest": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32"
}
后续步骤
- 了解如何修改、批准或拒绝更改请求，以及如何精选丰富代理批次。
- 了解如何请求单资源元数据更改。
- 详细了解治理工作流。