2026년 4월 10일부터 Dataplex Universal Catalog가 Knowledge Catalog로 변경되었습니다. API, 클라이언트 라이브러리, CLI, IAM 이름은 변경되지 않습니다. 자세한 내용은 Google Cloud Knowledge Catalog 소개를 참조하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

거버넌스 워크플로로 변경 요청 관리

이 문서에서는 요청자, 승인자, 워크플로 관리자가 Knowledge Catalog(이전의 Dataplex Universal Catalog)에서 거버넌스 요청을 관리하는 방법을 설명합니다.

시작하기 전에

거버넌스 워크플로를 사용하려면 필요한 API를 사용 설정했고 승인자와 관리자에게 필요한 Identity and Access Management(IAM) 역할과 권한이 있는지 확인합니다.

Dataplex API가 아직 사용 설정되지 않았으면 사용 설정합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기

API 사용 설정하기

필요한 역할

거버넌스 요청을 관리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

데이터 제품 액세스 요청을 승인하거나 거부합니다.
- Dataplex 데이터 제품 편집자(roles/dataplex.dataProductsEditor)
- Dataplex 데이터 제품 관리자(roles/dataplex.dataProductsAdmin)
메타데이터 변경 요청 검토 및 승인:
- Dataplex 카탈로그 관리자(roles/dataplex.catalogAdmin)
- Dataplex 워크플로 승인자(roles/dataplex.workflowApprover)
작성된 요청 보기 및 수정: Dataplex 변경 요청 소유자(roles/dataplex.changeRequestOwner)
보강 에이전트가 만든 요청 보기 및 수정: Dataplex 카탈로그 관리자(roles/dataplex.catalogAdmin)
모든 요청을 보고 모든 상태의 요청을 삭제합니다.
- Dataplex 워크플로 관리자(roles/dataplex.workflowAdmin)
- Dataplex 카탈로그 관리자(roles/dataplex.catalogAdmin)
승인자 이메일 알림을 구성합니다.
- Dataplex 카탈로그 관리자(roles/dataplex.catalogAdmin)
- Dataplex 카탈로그 편집자(roles/dataplex.catalogEditor)
- Dataplex 용어집 소유자(roles/dataplex.glossaryOwner)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

역할 및 권한에 대한 자세한 내용은 Knowledge Catalog IAM 역할을 참조하세요.

요청자로서 요청 관리

요청자는 데이터 제품에 대한 액세스 요청 또는 메타데이터 변경 제안과 같은 변경 요청을 시작합니다. 요청을 제출한 후 진행 상황을 모니터링하거나, 요청 세부정보를 보거나, 대기 중인 요청의 세부정보를 수정하거나, 승인 담당자가 조치를 취하기 전에 NEW 상태의 요청을 삭제할 수 있습니다.

작성된 요청 보기

만든 요청을 보거나 특정 요청을 검사하려면 다음을 수행합니다.

콘솔

Google Cloud 콘솔에서 Knowledge Catalog 거버넌스 워크플로 페이지로 이동합니다.

거버넌스 워크플로로 이동
내 요청 탭을 클릭하여 이전 요청 및 대기 중인 요청 목록을 확인합니다.

REST

작성한 요청을 나열하려면 changeRequests.list 메서드를 사용합니다.

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests?filter=author=USER_EMAIL"

특정 요청을 보려면 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)
USER_EMAIL: 이메일 주소입니다.
CHANGE_REQUEST_ID: 요청의 고유 ID입니다.

일괄 메타데이터 변경 요청의 경우 응답 필드를 검사하여 요청이 생성된 방법을 확인합니다.

사용자가 제출한 요청: author는 요청자의 이메일 주소이고 batchChangeMetadataRequest.description.job는 설정되지 않습니다.
보강 에이전트 생성 요청: author는 보강 에이전트 서비스 계정이고 batchChangeMetadataRequest.description.job.name는 보강 실행 ID로 설정됩니다.

요청 수정

대기 중인 요청이 NEW 또는 FAILED 상태인 동안 REST API를 사용하여 업데이트할 수 있습니다. FAILED 상태의 요청을 업데이트하면 상태가 NEW로 재설정되므로 승인 담당자가 다시 검토할 수 있습니다. 메타데이터 변경 요청을 수정할 수 있는 사용자는 요청이 생성된 방식에 따라 다릅니다.

사용자가 제출한 요청: 원래 작성자만 PATCH 요청을 전송하여 근거 또는 요청 페이로드를 업데이트할 수 있습니다.
보강 에이전트에서 생성된 요청: 작성자 외에도 검토자와 승인자는 요청이 NEW 또는 FAILED 상태인 동안 PATCH 요청을 전송하여 배치를 선별할 수 있습니다. 예를 들어 제안된 관점 값을 수정하거나 changes 배열에서 항목을 삭제할 수 있습니다. author 필드는 보강 에이전트 서비스 계정으로 유지됩니다.

대기 중인 변경 요청을 업데이트하려면 changeRequests.patch 메서드를 사용합니다.

요청 사유만 업데이트하려면 다음 PATCH 요청을 전송합니다.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "justification": "NEW_JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID?updateMask=justification"

일괄 메타데이터 변경 요청의 페이로드를 업데이트하려면 다음 PATCH 요청을 보냅니다.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "justification": "NEW_JUSTIFICATION",
    "batchChangeMetadataRequest": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "changes": [
        {
          "updateEntryRequest": {
            "entry": {
              "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/EXISTING_ENTRY_ID",
              "aspects": {
                "ASPECT_PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID": {
                  "data": {
                    "ASPECT_FIELD_NAME": "UPDATED_ASPECT_FIELD_VALUE"
                  }
                }
              }
            },
            "updateMask": "aspects",
            "aspectKeys": [
              "ASPECT_PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID"
            ]
          }
        }
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID?updateMask=batchChangeMetadataRequest.changes,justification"

다음을 바꿉니다.

PROJECT_ID:Google Cloud 프로젝트의 ID입니다.
LOCATION: 변경 요청이 있는 리전입니다(예: us-central1).
CHANGE_REQUEST_ID: 변경 요청의 고유 ID입니다.
NEW_JUSTIFICATION: 변경 요청에 대한 업데이트된 사유입니다.
ENTRY_GROUP_ID: 대상 항목 그룹의 ID입니다.
EXISTING_ENTRY_ID: 업데이트된 일괄 페이로드에 있는 항목의 ID입니다.
ASPECT_PROJECT_ID: 관점 유형이 포함된 프로젝트의 ID입니다.
ASPECT_LOCATION: 관점 유형의 위치입니다(예: us-central1 또는 global).
ASPECT_TYPE_ID: 업데이트 중인 관점 유형의 ID입니다.
ASPECT_FIELD_NAME: 업데이트할 관점 필드의 이름입니다.
UPDATED_ASPECT_FIELD_VALUE: 관점 필드의 업데이트된 값입니다.

요청 삭제

요청자는 NEW 상태의 요청만 삭제할 수 있습니다. 요청을 삭제하려면 다음을 수행합니다.

콘솔

Google Cloud 콘솔에서 Knowledge Catalog 거버넌스 워크플로 페이지로 이동합니다.

거버넌스 워크플로로 이동
내 요청 탭을 클릭합니다.
삭제하려는 요청이 포함된 행을 찾습니다. 필요한 경우 필터를 적용하여 항목을 분리합니다.
작업을 클릭한 다음 삭제를 클릭합니다.

REST

요청을 삭제하려면 changeRequests.delete 메서드를 사용합니다.

예를 들어 다음 DELETE 요청을 보냅니다.

curl -X DELETE \
  -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입니다.

승인 담당자로 요청 관리하기

승인자는 데이터 리소스에 대해 제출된 대기 중인 요청을 평가하고 조치를 취합니다.

알림

요청을 승인하거나 거부하면 Knowledge Catalog에서 결정을 처리하고 검토 의견과 함께 요청자에게 이메일 알림을 보냅니다. 일괄 요청의 경우 업데이트 프로세스가 완료된 후 Knowledge Catalog에서 이메일 알림을 전송합니다. 작성자가 서비스 계정인 경우 Knowledge Catalog에서 알림을 보내지 않습니다.

승인 고려사항

자신의 요청을 승인할 수 없습니다. 승인자는 다른 주 구성원이어야 하며 제안된 변경사항에 필요한 모든 쓰기 및 유형 사용 권한을 보유해야 합니다. 하지만 보강 에이전트는 신뢰도에 따라 자체 요청을 자동 승인하거나 검토를 위해 승인 담당자에게 제출할 수 있습니다. 보강 에이전트에서 생성된 일괄 메타데이터 변경 요청의 경우 요청이 NEW 또는 FAILED 상태인 동안 승인하기 전에 요청 페이로드를 수정할 수 있습니다.

대기 중인 요청 보기

검토 대기 중인 요청을 보려면 다음 단계를 따르세요.

콘솔

Google Cloud 콘솔에서 Knowledge Catalog 거버넌스 워크플로 페이지로 이동합니다.

거버넌스 워크플로로 이동
승인 대기 중 탭을 클릭하여 검토 대기 중인 요청을 확인합니다. 리소스 유형, 요청 유형 또는 날짜별로 요청을 필터링할 수 있습니다.

REST

특정 프로젝트 및 위치에서 검토 대기 중인 요청을 나열하려면 changeRequests.list 메서드를 사용합니다.

예를 들어 다음 GET 요청을 보냅니다.

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests?filter=state=NEW"

다음을 바꿉니다.

PROJECT_ID:Google Cloud 프로젝트의 ID입니다.
LOCATION: 리소스가 있는 리전(예: us-central1)

반환된 목록에서 일괄 메타데이터 변경 요청에는 changeType 필드가 BATCH_CHANGE_METADATA로 설정됩니다. 보강 에이전트 실행으로 생성된 요청에는 batchChangeMetadataRequest.description.job.name에 보강 실행 ID가 포함됩니다.

대기 중인 일괄 변경 요청의 샘플 응답

{
"changeRequests": [
  {
    "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
    "uid": "b326114f-472b-457d-81e8-98b8ad89c608",
    "justification": "Enrichment Agent Proposal: Batch Metadata Change",
    "author": "enrichment-agent@my-project.iam.gserviceaccount.com",
    "state": "NEW",
    "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "changeType": "BATCH_CHANGE_METADATA",
    "batchChangeMetadataRequest": {
      "name": "projects/my-project/locations/us-central1/entryGroups/my-entry-group",
      "description": {
        "job": {
          "name": "projects/123456789012/locations/us-central1/enrichmentTasks/my-enrichment-task/runs/55199e83-1a1e-4837-bb8c-c402c6bee641"
        }
      },
      "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"
            }
          }
        }
      ]
    }
  }
]
}

요청 승인

요청을 승인하려면 다음을 수행합니다.

콘솔

Google Cloud 콘솔에서 Knowledge Catalog 거버넌스 워크플로 페이지로 이동합니다.

거버넌스 워크플로로 이동
승인 대기 중 탭을 클릭합니다.
승인하려는 요청이 포함된 행을 찾습니다.
작업을 클릭한 다음 승인을 클릭합니다.

REST

요청을 승인하려면 changeRequests.approve 메서드를 사용합니다.

예를 들어 다음 POST 요청을 보냅니다.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID:approve"

다음을 바꿉니다.

PROJECT_ID:Google Cloud 프로젝트의 ID입니다.
LOCATION: 리소스가 있는 리전(예: us-central1)
CHANGE_REQUEST_ID: 승인하려는 변경 요청의 고유 ID입니다.

사용자 또는 보강 에이전트가 제출한 일괄 메타데이터 변경 요청을 승인하면 Knowledge Catalog가 IAM 권한 및 페이로드 규칙을 동기식으로 검증합니다.

검증에 성공하면 Knowledge Catalog가 백그라운드에서 배치를 실행하는 동안 메서드가 APPLYING 상태의 ChangeRequest를 반환합니다.

  {
    "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
    "uid": "b326114f-472b-457d-81e8-98b8ad89c608",
    "justification": "Proposing new entry using RequestBatchMetadataChange",
    "author": "requester@example.com",
    "state": "APPLYING",
    "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "approver": "approver@example.com",
    "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"
            }
          }
        }
      ]
    }
  }
  ```

* If synchronous payload validation fails (for example, with an
`INVALID_ARGUMENT` or `NOT_FOUND` error), the request immediately
transitions to the `FAILED` state instead of `APPLYING`.
* If permission validation fails with a `PERMISSION_DENIED` error, the request
remains in the `NEW` state.

After background execution finishes, poll `changeRequests.get` to check the
final state (`APPROVED` or `FAILED`). If any changes in the batch fail,
`batchChangeMetadataResponse.failedRequests` lists each failed change by its
position in `changes` (starting at `0`) along with the error details:

```json
{
  "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
  "state": "APPROVED",
  "changeType": "BATCH_CHANGE_METADATA",
  "batchChangeMetadataResponse": {
    "failedRequests": {
      "1": {
        "code": 5,
        "message": "Entry not found."
      }
    }
  }
}

요청 상태에 대한 자세한 내용은 거버넌스 워크플로 처리 경로를 참조하세요.

요청 거부

요청을 거부하려면 다음 단계를 따르세요.

콘솔

Google Cloud 콘솔에서 Knowledge Catalog 거버넌스 워크플로 페이지로 이동합니다.

거버넌스 워크플로로 이동
승인 대기 중 탭을 클릭합니다.
거부하려는 요청이 포함된 행을 찾습니다.
작업을 클릭한 다음 거부를 클릭합니다.
대화상자에 거부 사유를 입력합니다.
거부를 클릭하여 확인합니다.

REST

요청을 거부하려면 changeRequests.reject 메서드를 사용합니다.

예를 들어 다음 POST 요청을 보냅니다.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "REJECTION_REASON"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID:reject"

다음을 바꿉니다.

PROJECT_ID:Google Cloud 프로젝트의 ID입니다.
LOCATION: 리소스가 있는 리전(예: us-central1)
CHANGE_REQUEST_ID: 거부하려는 변경 요청의 고유 ID입니다.
REJECTION_REASON: 거부 사유입니다.

명확한 거부 의견을 제공하면 요청자가 결정을 이해하고 요청을 다시 제출하기 전에 근거를 수정하는 데 도움이 됩니다.

워크플로 관리자로 요청 관리

워크플로 관리자는 조직 전체의 거버넌스 요청을 감독하고, 승인자 이메일 알림을 구성하고, 승인 기록을 감사하고, 모든 상태의 요청을 삭제합니다.

승인 담당자 이메일 알림 구성하기

항목 그룹 또는 비즈니스 용어집에서 승인자 이메일 알림을 구성하여 해당 리소스에 대해 단일 또는 일괄 메타데이터 변경 요청이 생성될 때마다 자동으로 알림을 받는 이메일 주소를 최대 10개까지 지정할 수 있습니다.

항목 그룹에서 알림을 구성하려면 entryGroups.patch 메서드를 사용합니다.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "changeRequestConfig": {
      "approverEmails": [
        "APPROVER_EMAIL_1",
        "APPROVER_EMAIL_2"
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID?updateMask=changeRequestConfig"

비즈니스 용어집에서 알림을 구성하려면 glossaries.patch 메서드를 사용합니다.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "changeRequestConfig": {
      "approverEmails": [
        "APPROVER_EMAIL_1",
        "APPROVER_EMAIL_2"
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/glossaries/GLOSSARY_ID?updateMask=changeRequestConfig"

다음을 바꿉니다.

PROJECT_ID:Google Cloud 프로젝트의 ID입니다.
LOCATION: 항목 그룹의 위치(예: us-central1 또는 global)
ENTRY_GROUP_ID: 항목 그룹의 ID입니다.
GLOSSARY_ID: 비즈니스 용어집의 ID입니다.
APPROVER_EMAIL_1, APPROVER_EMAIL_2: 변경 요청이 생성될 때 알림을 받을 잠재적 승인자의 이메일 주소입니다. 이메일 주소는 최대 10개까지 지정할 수 있습니다.

모든 요청 보기 및 승인 기록 추적

상태 전반에서 모든 활성 및 이전 요청을 확인하여 워크플로를 모니터링하고 데이터 제품 액세스 및 메타데이터 변경사항을 감사할 수 있습니다.

콘솔

Google Cloud 콘솔에서 Knowledge Catalog 거버넌스 워크플로 페이지로 이동합니다.

거버넌스 워크플로로 이동
승인 로그 탭을 클릭하여 완료된 승인, 거부, 이전 감사 추적을 확인합니다.

REST

특정 프로젝트 및 위치 내의 모든 활성 및 이전 요청을 나열하려면 changeRequests.list 메서드를 사용합니다.

예를 들어 다음 GET 요청을 보냅니다.

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests"

다음을 바꿉니다.

PROJECT_ID:Google Cloud 프로젝트의 ID입니다.
LOCATION: 리소스가 있는 리전(예: us-central1)

모든 상태의 요청 삭제

NEW 상태의 요청만 삭제할 수 있는 요청자와 달리 워크플로 관리자는 Google Cloud 콘솔 또는 changeRequests.delete 메서드를 사용하여 모든 상태의 요청을 삭제할 수 있습니다. 자세한 내용은 요청 삭제를 참조하세요.

다음 단계

거버넌스 워크플로에 대해 자세히 알아보세요.
단일 리소스 메타데이터 변경을 요청하는 방법을 알아보세요.
메타데이터 일괄 변경을 요청하는 방법을 알아보세요.

거버넌스 워크플로로 변경 요청 관리 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필요한 역할

요청자로서 요청 관리

작성된 요청 보기

콘솔

REST

요청 수정

요청 삭제

콘솔

REST

승인 담당자로 요청 관리하기

알림

승인 고려사항

대기 중인 요청 보기

콘솔

REST

요청 승인

콘솔

REST

요청 거부

콘솔

REST

워크플로 관리자로 요청 관리

승인 담당자 이메일 알림 구성하기

모든 요청 보기 및 승인 기록 추적

콘솔

REST

모든 상태의 요청 삭제

다음 단계

거버넌스 워크플로로 변경 요청 관리