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

객체 보강 관리

객체 보강을 구성하면 Cloud Storage는 적격 객체를 비동기식으로 평가하고 보강 메타데이터를 저장된 객체에 직접 연결합니다.

이 페이지에서는 기본 컨텍스트 메타데이터를 검사하고, 확장된 데이터 페이로드를 검색하고, 객체에서 보강을 삭제하고, Cloud Monitoring에서 처리 진행 상황을 모니터링하는 방법을 설명합니다.

필요한 역할 가져오기

객체 보강을 보고, 검색하고, 삭제하는 데 필요한 권한을 얻으려면 관리자에게 버킷 또는 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

기본 객체 보강 메타데이터 보기: 스토리지 객체 뷰어 (roles/storage.objectViewer)
객체 보강 확장 데이터 검색: 스토리지 객체 사용자 (roles/storage.objectUser)
객체 재작성 중에 객체 보강 삭제: 스토리지 객체 관리자 (roles/storage.objectAdmin)

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

이러한 사전 정의된 역할에는 객체 보강을 보고, 검색하고, 삭제하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

객체 보강을 보고, 검색하고, 삭제하려면 다음 권한이 필요합니다.

기본 객체 보강 컨텍스트 메타데이터 보기: storage.objects.get
객체 보강 확장 데이터 검색: storage.objects.viewFullContext
객체 재작성 중에 객체 보강 삭제:
- storage.objects.get
- storage.objects.create
- storage.objects.delete
- storage.objects.update

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한 을 부여받을 수도 있습니다.

객체 보강 보기

Cloud Storage는 보강 메타데이터를 객체에 직접 연결합니다. Google 관리 객체 컨텍스트는 contexts.custom 속성 아래에 있습니다. 각 모델은 google:annotation: 프리픽스가 붙은 예약된 키를 사용합니다 (예: google:annotation:label-detector-v1 또는 google:annotation:face-detector-v1).

Cloud Storage는 보강 데이터를 두 가지 등급으로 구성합니다.

컨텍스트 메타데이터: 컨텍스트 키, 모델 실행 상태 (value), 타임스탬프, 프로토콜 버퍼 유형 URL을 포함합니다. 표준 객체 describe 및 get 작업은 이 메타데이터를 반환합니다.
확장 데이터 (미리보기): 전체 구조화된 JSON 보강 페이로드 (최대 128KiB)를 포함합니다. 이 페이로드에는 경계 다각형 좌표, 분류 신뢰도 점수, 표정, 안전 등급과 같은 세부정보가 포함됩니다.

기본 컨텍스트 메타데이터 보기

객체를 처리한 모델을 확인하고 기본 컨텍스트 메타데이터를 보려면 Google Cloud 콘솔 또는 JSON API를 사용하세요.

콘솔

Google Cloud 콘솔에서 Cloud Storage 버킷 페이지로 이동합니다.

버킷으로 이동
버킷 목록에서 검사하려는 객체가 포함된 버킷 이름을 클릭합니다.

객체 테이블의 커스텀 컨텍스트 열에는 객체를 처리한 각 모델 (콘텐츠 안전, 얼굴 감지기, 라벨 감지기, 객체 감지기 또는 PDF 분류)의 칩 이 표시됩니다.
개별 객체를 검사하려면 객체의 이름을 클릭합니다.
객체 세부정보 페이지에서 커스텀 컨텍스트 필드로 이동합니다. 필드에 칩이 여러 개 있는 경우 를 클릭하여 행을 펼칩니다.
포인터를 모델 칩 위로 가져가거나 모델 칩을 클릭하여 기본 컨텍스트 메타데이터를 봅니다.
- 컨텍스트 키: 예약된 모델 키(예: google:annotation:label-detector-v1)
- 컨텍스트 값: 모델 실행 상태 (SUCCESS 또는 FAILURE)
- 생성 시간 및 최종 수정 시간: Cloud Storage에서 보강을 생성하고 마지막으로 업데이트한 시간의 타임스탬프입니다.
- 구성 허브 보기: 객체 보강 페이지를 엽니다. 버킷의 객체 테이블에서 칩을 볼 때 컨텍스트 필터링 을 클릭하여 해당 컨텍스트별로 버킷의 객체를 필터링할 수도 있습니다.

JSON API

`Authorization` 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

cURL을 사용하여 projection=full 쿼리 매개변수가 포함된 Objects: get 요청을 JSON API로 보냅니다.

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?projection=full"

각 항목의 의미는 다음과 같습니다.

BUCKET_NAME은 객체가 포함된 버킷의 이름입니다. 예를 들면 my-bucket입니다.
OBJECT_NAME 은 객체의 URL 인코딩 이름입니다. 예를 들면 image.jpg입니다.

응답은 contexts.custom 구조를 반환합니다.

{
  "kind": "storage#object",
  "id": "my-bucket/image.jpg/1700000000000000",
  "name": "image.jpg",
  "bucket": "my-bucket",
  "contexts": {
    "custom": {
      "google:annotation:label-detector-v1": {
        "value": "SUCCESS",
        "createTime": "2026-09-29T17:20:00.000Z",
        "updateTime": "2026-09-29T17:20:00.000Z",
        "extendedDataTypeUrl": "type.googleapis.com/google.protobuf.Struct"
      }
    }
  }
}

value 필드는 객체의 모델 실행 상태(예: SUCCESS 또는 FAILURE)를 나타냅니다.

확장 데이터 검색

전체 구조화된 보강 데이터 (예: 경계 상자, 경계 다각형, 라벨 또는 감지된 얼굴)를 검색하려면 JSON API를 사용하여 viewFullContext 메서드 (미리보기)를 호출합니다.

`Authorization` 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

cURL을 사용하여 검사하려는 모델의 컨텍스트 키를 지정하여 viewFullContext 요청을 JSON API로 보냅니다 .

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/viewFullContext?contextKey=CONTEXT_KEY"

각 항목의 의미는 다음과 같습니다.

BUCKET_NAME 은 객체가 포함된 버킷의 이름입니다. 예를 들면 my-bucket입니다.
OBJECT_NAME은 객체의 URL 인코딩 이름입니다. 예를 들면 image.jpg입니다.
CONTEXT_KEY는 모델 컨텍스트 키입니다. 예를 들면 google:annotation:label-detector-v1입니다.

응답에는 전체 보강 페이로드가 포함된 extendedData 구조가 포함됩니다.

{
  "kind": "storage#objectFullContext",
  "type": "CUSTOM",
  "key": "google:annotation:label-detector-v1",
  "value": "SUCCESS",
  "createTime": "2026-09-29T17:20:00.000Z",
  "updateTime": "2026-09-29T17:20:00.000Z",
  "extendedData": {
    "@type": "type.googleapis.com/google.protobuf.Struct",
    "modelName": "label-detector",
    "modelVersion": "v1",
    "labelAnnotationGroup": {
      "labelAnnotations": [
        {
          "description": "Night",
          "knowledgeGraphId": "/m/01d74z",
          "score": 0.92,
          "topicality": 0.19
        }
      ]
    }
  }
}

각 모델의 자세한 JSON 스키마 및 필드는 지원되는 모델 및 스키마를 참조하세요.

객체 보강 삭제

데이터 보관 정책을 준수해야 하거나 더 이상 보강 메타데이터가 필요하지 않은 경우 객체에서 삭제할 수 있습니다.

Google은 google: 프리픽스로 시작하는 컨텍스트 키를 관리하므로 표준 메타데이터 업데이트 메서드를 사용하여 수정하거나 삭제할 수 없습니다. 대신 객체의 모든 객체 컨텍스트를 삭제하는 dropContextGroups=custom 매개변수를 지정하여 객체 재작성, 복사 또는 구성 작업 중에 삭제합니다.

JSON API를 사용하여 객체를 재작성할 때 객체 컨텍스트(객체 보강 포함) 을(를) 삭제하려면 다음 단계를 따르세요.

`Authorization` 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.
cURL을 사용하여 JSON API를 POST 재작성 객체 요청 및 dropContextGroups=custom 쿼리 매개변수로 호출합니다.
```
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Length: 0" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET/o/SOURCE_OBJECT/rewriteTo/b/DESTINATION_BUCKET/o/DESTINATION_OBJECT?dropContextGroups=custom"
```
각 항목의 의미는 다음과 같습니다.
- SOURCE_BUCKET 은 소스 객체가 포함된 버킷의 이름입니다. 예를 들면 my-source-bucket입니다.
- SOURCE_OBJECT 는 소스 객체의 URL 인코딩 이름입니다. 예를 들면 image.jpg입니다.
- DESTINATION_BUCKET 은 대상 버킷의 이름입니다 (소스 버킷과 일치할 수 있음). 예를 들면 my-source-bucket입니다.
- DESTINATION_OBJECT 는 대상 객체의 URL 인코딩 이름입니다 (소스 객체와 일치할 수 있음). 예를 들면 image.jpg입니다.

수십억 개의 객체에서 컨텍스트를 관리하고 삭제하려면 객체 컨텍스트 일괄 관리를 참조하세요.

객체 보강 측정항목 모니터링

Cloud Monitoring을 사용하여 보강 처리 처리량, 대기 중인 객체, 모델 실행 횟수를 추적할 수 있습니다. Cloud Storage는 모니터링 리소스 gcs_bucket의 storage.googleapis.com 네임스페이스 아래에 다음 측정항목을 내보냅니다.

측정항목 유형 (`storage.googleapis.com/` 프리픽스 사용)	종류 및 유형	설명 및 라벨
`auto_annotate/operations/pending_objects`	`GAUGE`, `INT64`	버킷에서 보강이 대기 중인 총 객체 수입니다. 300초마다 샘플링됩니다.
`auto_annotate/operations/processed_object_count`	`DELTA`, `INT64`	기간 동안 객체 보강으로 처리된 총 객체 수입니다. 300초마다 샘플링됩니다.
`auto_annotate/operations/model_count`	`DELTA`, `INT64`	기간 동안 버킷에서 실행된 총 모델 수입니다. `model_name`, `model_version`, `status` (예: `SUCCESS` 또는 `FAILURE`)별로 그룹화됩니다.
`auto_annotate/operations/request_count`	`DELTA`, `INT64`	기간 동안 이루어진 총 API 호출 수입니다. `method` 및 `response_code`별로 그룹화됩니다.
`auto_annotate/storage/annotated_objects`	`GAUGE`, `INT64`	`type` 및 `data_locations`별로 그룹화된 보강이 생성된 버킷의 총 객체 수의 일일 스냅샷입니다.
`auto_annotate/storage/model_outputs`	`GAUGE`, `INT64`	`model_name`, `model_version`, `status`, `type`, `data_locations`별로 그룹화된 버킷에 저장된 총 모델 출력 수의 일일 스냅샷입니다.

측정항목 쿼리 및 알림 설정에 대한 자세한 내용은 Cloud Storage용 Cloud Monitoring 측정항목 및 측정항목 탐색기로 차트 만들기를 참조하세요.