이 문서에서는 REST API를 사용하여 Knowledge Catalog(이전의 Dataplex Universal Catalog)에서 항목 그룹에 대한 일괄 메타데이터 변경 요청을 제출하는 방법을 설명합니다.
항목 그룹에 대한 직접 쓰기 액세스 권한이 없는 경우 항목 및 항목 링크에 대한 만들기, 업데이트, 삭제 작업을 최대 250개까지 단일 변경 요청으로 그룹화하여 검토 및 승인을 받을 수 있습니다.
시작하기 전에
일괄 메타데이터 변경 요청을 제출하려면 필요한 API를 사용 설정했고 대상 항목 그룹에 필요한 Identity and Access Management(IAM) 역할 및 권한이 있는지 확인합니다.
Dataplex API가 아직 사용 설정되지 않았으면 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기
필요한 역할
항목 그룹의 일괄 메타데이터 변경을 요청하는 데 필요한 권한을 얻으려면 관리자에게 대상 항목 그룹에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
일괄 메타데이터 변경 요청 제출: Dataplex 카탈로그 뷰어(
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: 항목 링크에서SOURCE로 사용되는 첫 번째 커스텀 항목의 ID입니다.SECOND_ENTRY_ID: 항목 링크에서TARGET로 사용되는 관점이 연결된 두 번째 커스텀 항목의 ID입니다.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"
}
다음 단계
- 변경 요청을 수정, 승인 또는 거부하고 보강 에이전트 배치를 선별하는 방법을 알아보세요.
- 단일 리소스 메타데이터 변경을 요청하는 방법 알아보기
- 거버넌스 워크플로에 대해 자세히 알아보세요.