이 페이지는 Cloud Translation API를 통해 번역되었습니다.

객체 컨텍스트 사용

이 페이지에서는 키-값 쌍 형식으로 Cloud Storage 객체에 컨텍스트를 연결하고 관리하는 방법을 설명합니다.

필요한 역할 가져오기

객체 컨텍스트를 만들고 관리하는 데 필요한 권한을 얻으려면 관리자에게 객체에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

컨텍스트를 사용하여 객체 만들기: 스토리지 객체 생성자 (roles/storage.objectCreator)
객체에서 컨텍스트를 연결, 업데이트, 보기, 삭제합니다. 스토리지 객체 사용자 (roles/storage.objectUser)
객체에 연결된 컨텍스트 키 및 값 보기: 스토리지 객체 뷰어 (roles/storage.objectViewer)

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

이러한 사전 정의된 역할에는 객체 컨텍스트를 만들고 관리하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

객체 컨텍스트를 만들고 관리하려면 다음 권한이 필요합니다.

객체 컨텍스트로 객체를 만듭니다.
- storage.objects.create
- storage.objects.createContext
객체 컨텍스트 연결, 업데이트, 삭제:
- storage.objects.update
- storage.objects.createContext
- storage.objects.updateContext
- storage.objects.deleteContext
객체 컨텍스트 보기:
- storage.objects.get
- storage.objects.list

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

새 객체에 컨텍스트 연결

Cloud Storage 버킷에 새 객체를 업로드할 때 객체에 컨텍스트를 연결합니다. 각 컨텍스트는 키와 값으로 구성됩니다.

명령줄

gcloud alpha storage cp 명령어로 객체를 업로드할 때 컨텍스트를 연결하려면 --custom-contexts 플래그를 사용합니다.

gcloud alpha storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME --custom-contexts=KEY=VALUE,...

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

OBJECT_LOCATION: 객체의 로컬 경로. 예를 들면 Desktop/dog.png입니다.
DESTINATION_BUCKET_NAME: 객체를 업로드할 버킷의 이름. 예를 들면 my-bucket입니다.
KEY은 객체에 연결할 컨텍스트 키입니다. 예를 들면 Department입니다. 쉼표로 구분된 여러 키-값 쌍을 지정할 수 있습니다.
VALUE은 컨텍스트 키와 연결할 값입니다. 예를 들면 Human resources입니다.

또는 객체에 연결할 컨텍스트가 포함된 JSON 파일을 만들고 --custom-contexts-file 플래그를 사용합니다.

  {
    "KEY": {
      "value": "VALUE"
    },
    ...
  }

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

KEY은 객체에 연결할 컨텍스트 키입니다. 예를 들면 Department입니다. 여러 키-값 쌍을 지정할 수 있습니다.
VALUE은 컨텍스트 키와 연결할 값입니다. 예를 들면 Human resources입니다.

gcloud alpha storage rsync 명령어로 디렉터리를 업로드할 때 컨텍스트를 첨부하려면 --custom-contexts 플래그 또는 --custom-contexts-file 플래그를 사용하세요.

gcloud alpha storage rsync DIRECTORY_LOCATION gs://DESTINATION_BUCKET_NAME --recursive --custom-contexts=KEY=VALUE,...

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

DIRECTORY_LOCATION은 디렉터리의 로컬 경로입니다. 예를 들면 ~/my_directory입니다.
DESTINATION_BUCKET_NAME은 디렉터리를 업로드할 버킷의 이름입니다. 예를 들면 my-bucket입니다.
KEY은 객체에 연결할 컨텍스트 키입니다. 예를 들면 Department입니다. 쉼표로 구분된 여러 키-값 쌍을 지정할 수 있습니다.
VALUE은 컨텍스트 키와 연결할 값입니다. 예를 들면 Human resources입니다.

JSON API

새 객체를 업로드할 때 객체에 컨텍스트를 연결하려면 다음 방법 중 하나를 사용하세요.

JSON 형식의 객체 메타데이터의 일부로 contexts 필드를 포함합니다.

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

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

KEY은 객체에 연결할 컨텍스트 키입니다. 예를 들면 Department입니다. custom 객체에 여러 키-값 쌍을 지정할 수 있습니다.
VALUE은 컨텍스트 키와 연결할 값입니다. 예를 들면 Human resources입니다.

기존 객체에 컨텍스트 연결 또는 수정

Cloud Storage 버킷의 기존 객체에 새 컨텍스트를 연결할 수 있습니다.

명령줄

gcloud alpha storage objects update 명령어를 사용합니다.

gcloud alpha storage objects update gs://BUCKET_NAME/OBJECT_NAME CUSTOM_CONTEXTS_FLAG

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

BUCKET_NAME은 컨텍스트를 수정하려는 객체가 포함된 버킷의 이름입니다. 예를 들면 my-bucket입니다.
OBJECT_NAME은 객체의 이름입니다. 예를 들면 pets/dog.png입니다.
CUSTOM_CONTEXTS_FLAG은 다음 플래그 중 하나입니다.
- 기존 컨텍스트를 모두 바꾸려면 --custom-contexts=KEY=VALUE,... 또는 --custom-contexts-file=CUSTOM_CONTEXTS_FILE를 사용하세요.
  
  각 항목의 의미는 다음과 같습니다.
  - KEY은 객체에 연결할 컨텍스트 키입니다. 예를 들면 Department입니다. 쉼표로 구분된 여러 키-값 쌍을 지정할 수 있습니다.
  - VALUE는 컨텍스트 키와 연결할 값입니다. 예를 들면 Human resources입니다.
  - CUSTOM_CONTEXTS_FILE은 객체에 연결할 컨텍스트가 포함된 JSON 또는 YAML 파일의 경로입니다.
- 기존 컨텍스트를 모두 삭제하려면 --clear-custom-contexts를 사용합니다.
- 개별 컨텍스트를 추가, 수정 또는 삭제하려면 --update-custom-contexts=KEY=VALUE,... 및 --remove-custom-contexts=KEY,...를 함께 사용합니다.
  
  각 항목의 의미는 다음과 같습니다.
  - KEY은 객체에 연결하거나 객체에서 삭제하려는 컨텍스트 키입니다. 예를 들면 Department입니다.
  - VALUE는 객체에 연결할 컨텍스트 키와 연결할 값입니다. 예를 들면 Human resources입니다.

성공하면 응답은 다음 예시와 같습니다.

Patching gs://my-bucket/pets/dog.png#1560574162144861...
  Completed 1

클라이언트 라이브러리

Java

자세한 내용은 Cloud Storage Java API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.collect.Maps;
import java.util.Map;

public class SetObjectContexts {
  public static void setObjectContexts(
      String projectId, String bucketName, String objectName, String key, String value)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The context key-value you want to add
    // String key = "your-context-key";
    // String value = "your-context-value";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {
      BlobId blobId = BlobId.of(bucketName, objectName);
      Blob blob = storage.get(blobId);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }

      // Recommended: Set a generation-match precondition to avoid potential race
      // conditions and data corruptions. The request to update returns a 412 error if
      // the object's generation number does not match your precondition.
      Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();

      // This section demonstrates how to upsert, delete all, and delete a specific context.

      // To upsert a context (if the key already exists, its value is replaced;
      // otherwise, a new key-value pair is added):
      ObjectCustomContextPayload payload =
          ObjectCustomContextPayload.newBuilder().setValue(value).build();
      Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
      custom.put(key, payload);
      ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();

      /*
       * To delete all existing contexts:
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(null).build();
       */

      /*
       * To delete a specific key from the context:
       * Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
       * custom.put(key, null);
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();
       */
      BlobInfo pendingUpdate = blob.toBuilder().setContexts(contexts).build();
      storage.update(pendingUpdate, precondition);

      System.out.println(
          "Updated custom contexts for object " + objectName + " in bucket " + bucketName);
    }
  }
}

JSON API

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

객체에 대한 설정이 포함된 JSON 파일을 만듭니다. 여기에는 객체에 대한 contexts 구성 필드가 포함되어야 합니다.

기존 컨텍스트를 추가, 수정 또는 덮어쓰려면 다음 형식을 사용하세요.

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

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

KEY은 객체에 연결할 컨텍스트 키입니다. 예를 들면 Department입니다. custom 객체에 키-값 쌍을 여러 개 지정할 수 있습니다.
VALUE는 컨텍스트 키와 연결할 값입니다. 예를 들면 Human resources입니다.

기존 컨텍스트를 모두 삭제하려면 다음 형식을 사용하세요.

  {
    "contexts": {
      "custom": null
    }
  }

컨텍스트에서 특정 키를 삭제하려면 다음 형식을 사용하세요.

  {
    "contexts": {
      "custom": {
        "KEY": null,
        ...
      }
    }
  }

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

KEY은 객체에서 삭제하려는 컨텍스트 키입니다. 예를 들면 Department입니다. custom 객체에서 삭제할 키를 여러 개 지정할 수 있습니다.

cURL을 사용하여 PATCH 객체 요청으로 JSON API를 호출합니다.
```
curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"
```
각 항목의 의미는 다음과 같습니다.
- JSON_FILE_NAME은 객체 컨텍스트 정보가 포함된 파일의 경로입니다.
- BUCKET_NAME은 컨텍스트를 수정하려는 객체가 포함된 버킷의 이름입니다. 예를 들면 my-bucket입니다.
- OBJECT_NAME은 객체의 URL 인코딩 이름입니다. 예를 들어 pets/dog.png는 pets%2Fdog.png로 URL 인코딩됩니다.

또는 객체의 컨텍스트를 PUT 객체 요청으로 바꿀 수 있습니다. PUT 객체 요청은 다른 객체 메타데이터도 대체합니다. 따라서 PUT 객체 요청은 사용하지 않는 것이 좋습니다.

객체 컨텍스트 보기

객체 메타데이터를 나열하거나 특정 객체를 설명하여 객체의 컨텍스트를 볼 수 있습니다.

명령줄

gcloud alpha storage objects describe 명령어를 사용합니다.

gcloud alpha storage objects describe gs://BUCKET_NAME/OBJECT_NAME

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

BUCKET_NAME은 컨텍스트를 보려는 객체가 포함된 버킷의 이름입니다. 예를 들면 my-bucket입니다.
OBJECT_NAME은 컨텍스트를 보려는 객체의 이름입니다. 예를 들면 pets/dog.png입니다.

성공하면 다음 예시와 비슷한 응답이 표시됩니다.

bucket: my-bucket
contexts:
  Department:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: HR
  DataClassification:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Confidential
name: employees.txt

클라이언트 라이브러리

Java

자세한 내용은 Cloud Storage Java API 참고 문서를 확인하세요.

Cloud Storage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetObjectContexts {
  public static void getObjectContexts(String projectId, String bucketName, String objectName)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {

      Blob blob = storage.get(bucketName, objectName);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }
      ObjectContexts objectContexts = blob.getContexts();

      if (objectContexts != null) {
        Map<String, ObjectCustomContextPayload> customContexts = objectContexts.getCustom();
        if (customContexts == null) {
          System.out.println("No custom contexts found for object: " + objectName);
          return;
        }
        // Print blob's object contexts
        System.out.println("\nCustom Contexts:");
        for (Map.Entry<String, ObjectCustomContextPayload> custom : customContexts.entrySet()) {
          System.out.println(custom.getKey() + "=" + custom.getValue());
        }
      }
    }
  }
}

JSON API

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

cURL을 사용하여 GET 객체 요청으로 JSON API를 호출합니다.

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

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

BUCKET_NAME은 컨텍스트를 보려는 객체가 포함된 버킷의 이름입니다. 예를 들면 my-bucket입니다.
OBJECT_NAME은 컨텍스트를 보려는 객체의 URL로 인코딩된 이름입니다. 예를 들어 pets/dog.png는 pets%2Fdog.png로 URL 인코딩됩니다.

성공하면 다음 예시와 비슷한 응답이 표시됩니다.

  {
    "kind": "storage#object",
    "name": "employees.txt",
    "bucket": "my-bucket",
    "contexts": {
      "custom": {
        "Department": {
          "value": "HR",
          "createTime": "2023-01-01T00:00:00.000Z",
          "updateTime": "2023-01-01T00:00:00.000Z"
        },
        "DataClassification": {
          "value": "Confidential",
          "createTime": "2023-01-01T00:00:00.000Z",
          "updateTime": "2023-01-01T00:00:00.000Z"
        }
      }
    }
  }

컨텍스트별로 객체 필터링

객체 컨텍스트 키의 존재 여부 또는 특정 값을 기준으로 객체를 필터링합니다. 컨텍스트별로 객체를 필터링하면 특정 객체 그룹을 효율적으로 찾고 관리할 수 있습니다. 자세한 내용은 컨텍스트별로 객체 필터링하기를 참고하세요.

객체 작업 중 객체 컨텍스트 관리

객체를 복사, 재작성, 구성, 이동 또는 복원할 때 객체 컨텍스트는 기본적으로 보존됩니다. 복사, 재작성, 작성 작업 중에 컨텍스트를 수정할 수도 있습니다.

명령줄

gcloud alpha storage cp 명령어, gcloud alpha storage rsync 명령어, gcloud alpha storage mv 명령어는 기본적으로 소스 객체의 컨텍스트를 보존합니다. 이러한 작업 중에 컨텍스트를 수정하려면 다음 플래그 중 하나를 사용하세요.

대상 객체의 새 컨텍스트를 설정하는 --custom-contexts 또는 --custom-contexts-file 플래그입니다.
소스 객체의 컨텍스트가 대상 객체에 연결되지 않도록 하는 --clear-custom-contexts 플래그
--update-custom-contexts 및 --remove-custom-contexts 플래그의 조합으로, 소스 객체에서 개별 컨텍스트를 수정하여 대상 객체에 연결합니다.

gcloud alpha storage objects compose 명령어는 소스 객체의 컨텍스트를 병합하고 기본적으로 대상 객체에 연결합니다. Cloud Storage는 나중에 처리된 소스 객체의 컨텍스트에 우선순위를 부여하여 충돌을 해결합니다. Compose 작업 중 객체 컨텍스트 동작에 관한 자세한 내용은 복합 객체 컨텍스트를 참고하세요. --custom-contexts 또는 --custom-contexts-file 플래그를 사용하여 대상 객체의 새 컨텍스트를 지정할 수도 있습니다.

JSON API

복사 또는 재작성 객체 작업 중에 컨텍스트를 수정하려면 요청 본문에 contexts.custom 속성을 포함합니다. 이 속성을 포함하지 않으면 소스 객체의 컨텍스트가 기본적으로 유지됩니다.
객체를 구성하면 소스 객체의 컨텍스트가 기본적으로 대상 객체로 병합됩니다. Cloud Storage는 나중에 처리된 소스 객체의 컨텍스트에 우선순위를 부여하여 충돌을 해결합니다. 구성 작업 중 객체 컨텍스트 동작에 대한 자세한 내용은 복합 객체 컨텍스트를 참고하세요. destination.contexts.custom 속성에서 대상 객체의 새 컨텍스트를 지정할 수도 있습니다.

다음 단계

Cloud Storage API 문서에서 객체 컨텍스트 속성에 대해 알아봅니다.