Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

オブジェクトエンリッチメントを管理する

オブジェクトエンリッチメントを構成すると、Cloud Storage は対象となるオブジェクトを非同期で評価し、エンリッチメントメタデータを保存済みオブジェクトに直接追加します。

このページでは、基本的なコンテキストメタデータを検査する方法、拡張データペイロードを取得する方法、オブジェクトからエンリッチメントを破棄する方法、Cloud Monitoring で処理の進行状況をモニタリングする方法について説明します。

必要なロールを取得する

オブジェクトエンリッチメントを表示、取得、破棄するために必要な権限を取得するには、バケットまたはプロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

基本的なオブジェクトエンリッチメントメタデータを表示する: Storage オブジェクト閲覧者（roles/storage.objectViewer）
オブジェクトの拡充拡張データを取得する: Storage オブジェクトユーザー（roles/storage.objectUser）
オブジェクトの書き換え中にオブジェクトエンリッチメントを破棄する: Storage オブジェクト管理者（roles/storage.objectAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、オブジェクトエンリッチメントの表示、取得、破棄に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

オブジェクトエンリッチメントを表示、取得、破棄するには、次の権限が必要です。

基本的なオブジェクトエンリッチメントのコンテキストメタデータを表示する: storage.objects.get
オブジェクトエンリッチメントの拡張データを取得します。 storage.objects.viewFullContext
オブジェクトの書き換え中にオブジェクトエンリッチメントを破棄する:
- storage.objects.get
- storage.objects.create
- storage.objects.delete
- storage.objects.update

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

オブジェクトエンリッチメントを表示する

Cloud Storage は、contexts.custom プロパティの下に Google が管理するオブジェクトコンテキストとして、エンリッチメントメタデータをオブジェクトに直接アタッチします。各モデルは、google:annotation: という接頭辞が付いた予約済みのキー（google:annotation:label-detector-v1 や google:annotation:face-detector-v1 など）を使用します。

Cloud Storage では、拡充データが 2 つの階層に整理されます。

コンテキストメタデータ: コンテキストキー、モデル実行ステータス（value）、タイムスタンプ、protobuf タイプ URL が含まれます。標準オブジェクトの describe オペレーションと get オペレーションは、このメタデータを返します。
拡張データ（プレビュー）: 構造化された JSON エンリッチメントペイロード全体（最大 128 KiB）が含まれます。このペイロードには、境界ポリゴンの座標、分類の信頼スコア、表情、安全性評価などの詳細が含まれます。

基本的なコンテキストメタデータを表示する

オブジェクトを処理したモデルを確認し、基本的なコンテキストメタデータを表示するには、 Google Cloud コンソールまたは JSON API を使用します。

コンソール

Google Cloud コンソールで Cloud Storage の [バケット] ページに移動します。
[バケット] に移動
バケットのリストで、検査するオブジェクトを含むバケットの名前をクリックします。

[オブジェクト] テーブルの [カスタムコンテキスト] 列には、オブジェクトを処理した各モデル（コンテンツセーフティ、顔検出機能、ラベル検出機能、オブジェクト検出機能、PDF 分類）のチップが表示されます。
個々のオブジェクトを調べるには、オブジェクトの名前をクリックします。
[オブジェクトの詳細] ページで、[カスタムコンテキスト] フィールドに移動します。フィールドに複数のチップがある場合は、をクリックして行を開きます。
モデルチップにカーソルを合わせるか、クリックして、基本的なコンテキストメタデータを表示します。
- コンテキストキー: 予約済みのモデルキー（google:annotation:label-detector-v1 など）。
- コンテキスト値: モデルの実行ステータス（SUCCESS または FAILURE）。
- 作成時間と最終更新時間: Cloud Storage がエンリッチメントを作成して最後に更新したときのタイムスタンプ。
- 構成ハブを表示: [オブジェクトの拡充] ページが開きます。バケットの [オブジェクト] テーブルからチップを表示するときに、[コンテキストをフィルタ] をクリックして、そのコンテキストでバケット内のオブジェクトをフィルタすることもできます。

JSON API

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

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 メソッド（プレビュー）を呼び出します。

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

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 を使用してオブジェクトを書き換えるときに、オブジェクトコンテキスト（オブジェクトエンリッチメントを含む）を破棄するには、次の操作を行います。

gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセストークンを生成できます。
cURL を使用して、POST rewrite Object リクエストと dropContextGroups=custom クエリパラメータで JSON API を呼び出します。
```
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 Namespace で次の指標をエクスポートします。

指標タイプ（`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 指標と Metrics Explorer でグラフを作成するをご覧ください。

オブジェクト エンリッチメントを管理する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

必要なロールを取得する

必要な権限

オブジェクト エンリッチメントを表示する

基本的なコンテキスト メタデータを表示する