オブジェクトコンテキストを使用する

このページでは、Cloud Storage オブジェクトに Key-Value ペアの形式でコンテキストを関連付けて管理する方法について説明します。

必要なロールを取得する

オブジェクトコンテキストの作成と管理に必要な権限を取得するには、オブジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

コンテキストを使用してオブジェクトを作成する: Storage オブジェクト作成者（roles/storage.objectCreator）
オブジェクトのコンテキストの追加、更新、表示、削除: Storage オブジェクトユーザー（roles/storage.objectUser）
オブジェクトに付加されたコンテキストキーと値を表示する: Storage オブジェクト閲覧者（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 バケットにアップロードするときに、オブジェクトにコンテキストを関連付けます。各コンテキストはキーと値で構成されます。

JSON API

新しいオブジェクトをアップロードするときにコンテキストをオブジェクトに関連付けるには、次のいずれかの方法を使用します。

既存のオブジェクトにコンテキストを関連付ける、またはコンテキストを変更する

Cloud Storage バケット内の既存のオブジェクトに新しいコンテキストを関連付けることができます。

JSON API

gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセストークンを生成できます。

オブジェクトの設定を含む JSON ファイルを作成します。この設定には、オブジェクトの contexts 構成フィールドを含める必要があります。

既存のコンテキストを追加、変更、または上書きするには、次の形式を使用します。

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

ここで

KEY は、オブジェクトに付加するコンテキストキーです。例: Departmentcustom オブジェクトには複数の Key-Value ペアを指定できます。
VALUE は、コンテキストキーに関連付ける値です。例: Human resources

既存のコンテキストをすべて削除するには、次の形式を使用します。
```
{
  "contexts": {
    "custom": null
  }
}
```
コンテキストから特定のキーを削除するには、次の形式を使用します。
```
{
  "contexts": {
    "custom": {
      "KEY": null,
      ...
    }
  }
}
```
ここで

KEY は、オブジェクトから削除するコンテキストキーです。例: Departmentcustom オブジェクトから削除する複数のキーを指定できます。

cURL を使用して PATCH Object リクエストで 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 Object リクエストで置き換えることもできます。PUT Object リクエストは、他のオブジェクトメタデータも置き換えます。そのため、PUT Object リクエストの使用はおすすめしません。

オブジェクトコンテキストを表示する

オブジェクトのコンテキストを表示するには、オブジェクトのメタデータを一覧表示するか、特定のオブジェクトを記述します。

JSON API

gcloud CLI をインストールして初期化します。これにより、Authorization ヘッダーのアクセストークンを生成できます。

cURL を使用して、GET Object リクエストで 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%2Fdog.png と URL エンコードした pets/dog.png です。

正常に終了すると、レスポンスは次の例のようになります。

  {
    "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"
        }
      }
    }
  }

コンテキストでオブジェクトをフィルタする

オブジェクトコンテキストキーの存在またはその特定の値でオブジェクトをフィルタします。コンテキストでオブジェクトをフィルタすると、特定のオブジェクトグループを効率的に見つけて管理できます。詳細については、オブジェクトコンテキストでフィルタするをご覧ください。

オブジェクトオペレーション時にオブジェクトコンテキストを管理する

オブジェクトをコピー、書き換え、作成、移動、復元すると、オブジェクトコンテキストはデフォルトで保持されます。コピー、書き換え、作成のオペレーション中にコンテキストを変更することもできます。

JSON API

コピーまたは書き換えのオブジェクトオペレーション中にコンテキストを変更するには、リクエストの本文に contexts.custom プロパティを含めます。このプロパティを含めない場合、ソースオブジェクトのコンテキストはデフォルトで保持されます。
オブジェクトを作成すると、デフォルトでソースオブジェクトのコンテキストが宛先オブジェクトにマージされます。Cloud Storage は、後で処理されたソースオブジェクトのコンテキストを優先することで、競合を解決します。作成オペレーション中のオブジェクトコンテキストの動作について詳しくは、複合オブジェクトコンテキストをご覧ください。destination.contexts.custom プロパティで、宛先オブジェクトの新しいコンテキストを指定することもできます。

次のステップ

オブジェクトコンテキストプロパティについては、Cloud Storage API ドキュメントをご覧ください。

オブジェクト コンテキストを使用する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

必要なロールを取得する

必要な権限

新しいオブジェクトにコンテキストを関連付ける

JSON API

既存のオブジェクトにコンテキストを関連付ける、またはコンテキストを変更する

JSON API

オブジェクト コンテキストを表示する

JSON API

コンテキストでオブジェクトをフィルタする

オブジェクト オペレーション時にオブジェクト コンテキストを管理する

JSON API

次のステップ

オブジェクトコンテキストを使用する

オブジェクトコンテキストを表示する

オブジェクトオペレーション時にオブジェクトコンテキストを管理する