객체 컨텍스트 사용

명령줄

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입니다.

명령줄

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

클라이언트 라이브러리

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

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

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

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

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

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

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

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

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

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

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

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

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

3. 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.s3nsapis.fr/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

클라이언트 라이브러리

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

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

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

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.s3nsapis.fr/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 속성에서 대상 객체의 새 컨텍스트를 지정할 수도 있습니다.