使用物件內容

物件內容是可附加至 Cloud Storage 物件的自訂鍵/值組合。您可以使用物件脈絡資料分類資料、追蹤處理工作流程，以及為物件充實中繼資料。複製、撰寫或還原物件時，這些內容會保留。

本頁面說明如何附加及管理 Cloud Storage 物件的背景資訊。

取得必要角色

如要取得建立及管理物件內容所需的權限，請要求管理員授予您物件的下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備建立及管理物件內容所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立及管理物件內容，必須具備下列權限：

  • 建立含有物件內容的物件：
    • storage.objects.create
    • storage.objects.createContext
  • 附加、更新及刪除物件脈絡資料：
    • storage.objects.update
    • storage.objects.createContext
    • storage.objects.updateContext
    • storage.objects.deleteContext
  • 放置物件內容： storage.objects.dropContexts
  • 查看物件結構定義：
    • storage.objects.get
    • storage.objects.list
  • 查看物件的完整背景資訊，包括擴充資料 (預先發布版)： storage.objects.viewFullContext

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

鍵/值組合的命名規定

自訂情境的鍵和值都必須符合下列規定：

  • 長度必須介於 1 至 256 個半形字元之間。

  • 開頭須為英數字元。

  • 必須是有效的 UTF-8 字元。系統支援大多數 UTF-8 字元，但下列字元除外：

    • 單引號 (')

    • 雙引號 (")

    • 反斜線 (\)

    • 正斜線 (/)

  • 開頭為前置字串 google: 的脈絡資料鍵 (例如 google:annotation:face-detector-v1) 會預留給 Google 產生的脈絡。您無法建立含有 google: 前置字元的新情境，也無法修改其值。如果嘗試這麼做，Cloud Storage 會傳回 INVALID_ARGUMENT 錯誤。如要移除前置字元為 google: 的結構定義，請在重寫作業期間使用 dropContextGroups 參數捨棄這些結構定義。

將背景資訊附加至新物件

將新物件上傳至 Cloud Storage bucket 時，請將背景資訊附加至物件。每個情境都包含一個鍵和一個值。

控制台

  1. 前往 Cloud de Confiance 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 上傳物件。

  3. 按照步驟將情境附加至物件。

指令列

如要使用 gcloud storage cp 指令上傳物件時附加背景資訊，請使用 --custom-contexts 旗標：

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

其中：

  • OBJECT_LOCATION 是物件的本機路徑。例如：Desktop/employees.txt。
  • DESTINATION_BUCKET_NAME 是您要上傳物件的 bucket 名稱。例如：my-bucket。
  • KEY 是要附加至物件的內容鍵。 例如，Department。您可以指定多個鍵/值組合，並以半形逗號分隔。
  • VALUE 是要與情境索引鍵建立關聯的值。例如：Human resources。

或者，建立包含要附加至物件的內容的 JSON 檔案，並使用 --custom-contexts-file 旗標：

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

其中：

  • KEY 是要附加至物件的脈絡資料鍵。例如，Department。您可以指定多個鍵/值組合。
  • VALUE 是要與情境索引鍵建立關聯的值。例如：Human resources。

如要使用 gcloud storage rsync 指令上傳目錄時附加環境，請使用 --custom-contexts 旗標或 --custom-contexts-file 旗標：

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

其中：

  • DIRECTORY_LOCATION 是目錄的本機路徑。例如：~/my_directory。
  • DESTINATION_BUCKET_NAME 是您要上傳目錄的 bucket 名稱。例如：my-bucket。
  • KEY 是要附加至物件的情境金鑰。例如，Department。您可以指定多個鍵/值組合，並以半形逗號分隔。
  • VALUE 是要與內容鍵建立關聯的值。例如：Human resources。

JSON API

如要在上傳新物件時將情境附加至物件，請使用下列任一方法：

以 JSON 格式提供物件中繼資料時，請加入 contexts 欄位：

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

其中：

  • KEY 是要附加至物件的內容鍵。 例如，Department。您可以在 custom 物件中指定多個鍵/值組合。
  • VALUE 是要與情境索引鍵建立關聯的值。例如：Human resources。

在現有物件上附加或修改脈絡資料

您可以將新內容附加至物件，或更新 Cloud Storage bucket 中的現有內容。

只有 Google 服務 (例如 object enrichments 工作) 才能產生及附加含有擴充資料的情境，這些資料會使用保留的 google: 鍵前置字串。您無法將擴充資料附加至使用者定義的情境，也無法建立或修改開頭為 google: 前置字串的情境索引鍵。如果您嘗試建立或修改 google: 金鑰，Cloud Storage 會傳回 INVALID_ARGUMENT 錯誤。

如果現有內容包含擴充資料，Cloud Storage 會在更新和修補作業期間，保留更新物件的內容。如果將情境值設為 null，系統只會刪除沒有擴充資料的情境。如要查看擴充資料，請參閱「查看完整物件內容」。如要移除含有擴充資料的脈絡 (包括前置字串為 google: 的脈絡)，您必須在重寫作業期間使用 dropContextGroups 參數捨棄該脈絡。

控制台

  1. 前往 Cloud de Confiance 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，點選含有物件的 bucket 名稱。

  3. 前往物件，然後按一下 「Open object overflow menu」(開啟物件溢位選單)。

  4. 按一下「Edit contexts」。

  5. 在「Edit contexts」(編輯情境) 面板中，執行下列任一操作：

    • 新增物件脈絡資料：

      1. 按一下「新增自訂脈絡資料」。

      2. 在「Object context key」(物件內容鍵) 和「Object context value」(物件內容值) 欄位中，輸入新的鍵/值組合。

      3. 按一下「完成」。

      4. 選用：如要新增其他物件內容，請按一下「新增自訂內容」，重複上述步驟，然後按一下「儲存」。

    • 編輯物件情境：

      1. 按一下物件脈絡資料。

      2. 更新「物件脈絡資料鍵」欄位、「物件脈絡資料值」欄位，或同時更新這兩個欄位。

      3. 依序按一下 [完成] 及 [儲存]。

    • 刪除物件內容：

      依序點按「刪除」和「儲存」。

指令列

使用 gcloud storage objects update 指令：

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

其中：

  • BUCKET_NAME 是 bucket 的名稱，其中包含要編輯內容的物件。例如：my-bucket。
  • OBJECT_NAME 是物件的名稱。例如：employees.txt。

  • 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/employees.txt#1560574162144861...
  Completed 1

用戶端程式庫

Java

詳情請參閱「Cloud Storage Java API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

執行程式碼範例前，請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。


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);
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;
use google_cloud_storage::model::ObjectContexts;
use google_cloud_wkt::FieldMask;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "object-with-contexts";
    let object = client
        .get_object()
        .set_bucket(format!("projects/_/buckets/{bucket_id}"))
        .set_object(NAME)
        .send()
        .await?;

    let metageneration = object.metageneration;
    let mut custom = object.contexts.clone().unwrap_or_default().custom;
    custom.entry("example".to_string()).or_default().value = "true".into();

    let updated = client
        .update_object()
        .set_if_metageneration_match(metageneration)
        .set_object(object.set_contexts(ObjectContexts::new().set_custom(custom)))
        .set_update_mask(FieldMask::default().set_paths(["contexts.custom.example"]))
        .send()
        .await?;
    println!(
        "successfully set contexts for object {NAME} in bucket {bucket_id}: {:?}",
        updated.contexts
    );
    Ok(())
}

JSON API

  1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

  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 呼叫 JSON API，並發出 PATCH 物件要求：

    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 是包含要編輯內容的物件所屬的 bucket 名稱。例如：my-bucket。
    • OBJECT_NAME 是物件的網址編碼名稱。例如：employees.txt。

或者，您也可以使用 PUT 物件要求，取代物件的背景資訊。PUT 物件要求也會取代其他物件中繼資料。因此，我們不建議使用 PUT 物件要求。

查看物件脈絡資料

如要查看物件的脈絡資料，可以列出物件中繼資料，或描述特定物件。

控制台

  1. 前往 Cloud de Confiance 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，點選含有要查看內容的物件所屬 bucket 名稱。

  3. 前往物件，然後按一下物件名稱。

    在「Object details」(物件詳細資料) 頁面中，「Object contexts」(物件內容) 區段會列出所有附加內容的鍵/值組合。

指令列

使用 gcloud storage objects describe 指令：

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME

其中：

  • BUCKET_NAME 是包含物件的 bucket 名稱。例如：my-bucket。
  • OBJECT_NAME 是物件的名稱。例如：employees.txt。

如果成功，回應會類似以下範例：

bucket: my-bucket
contexts:
  custom:
    Department:
      createTime: '2023-01-01T00:00:00.000000+00:00'
      type: CUSTOM
      updateTime: '2023-01-01T00:00:00.000000+00:00'
      value: Human resources
    google:annotation:face-detector-v1:
      createTime: '2025-09-29T17:20:00.000000+00:00'
      extendedDataTypeUrl: type.googleapis.com/google.protobuf.Struct
      type: CUSTOM
      updateTime: '2025-09-29T17:20:00.000000+00:00'
      value: SUCCESS
name: employees.txt

用戶端程式庫

Java

詳情請參閱「Cloud Storage Java API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

執行程式碼範例前，請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。


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());
        }
      }
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "object-with-contexts";
    let object = client
        .get_object()
        .set_bucket(format!("projects/_/buckets/{bucket_id}"))
        .set_object(NAME)
        .send()
        .await?;
    println!(
        "The contexts field for object {NAME} in bucket {bucket_id} is: {:?}",
        object.contexts
    );
    Ok(())
}

JSON API

  1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

  2. 使用 cURL 呼叫 JSON API，並傳送 GET 物件要求：

    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 是物件的網址編碼名稱。例如：employees.txt。

    如果成功，回應會類似以下範例：

      {
    "kind": "storage#object",
    "name": "employees.txt",
    "bucket": "my-bucket",
    "contexts": {
      "custom": {
        "Department": {
          "value": "Human resources",
          "createTime": "2023-01-01T00:00:00.000Z",
          "updateTime": "2023-01-01T00:00:00.000Z"
        },
        "google:annotation:face-detector-v1": {
          "value": "SUCCESS",
          "createTime": "2025-09-29T17:20:00.000Z",
          "updateTime": "2025-09-29T17:20:00.000Z",
          "extendedDataTypeUrl": "type.googleapis.com/google.protobuf.Struct"
        }
      }
    }
  }

查看完整物件脈絡資料

如要查看單一情境及其擴充資料，請使用 viewFullContext 方法 (預先發布版)。

JSON API

如要依鍵擷取單一完整內容 (包括擴充資料)：

  1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

  2. 使用 cURL 呼叫 JSON API，並發出 GET View Full Context 要求：

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/viewFullContext?contextKey=KEY"

    其中：

    • BUCKET_NAME 是包含物件的值區名稱。例如：my-bucket。
    • OBJECT_NAME 是物件的網址編碼名稱。例如：employees.txt。
    • KEY 是要擷取的特定內容鍵。例如：google:annotation:face-detector-v1。

    如果成功，回應會類似以下範例：

    {
  "kind": "storage#objectFullContext",
  "type": "CUSTOM",
  "key": "google:annotation:face-detector-v1",
  "value": "SUCCESS",
  "createTime": "2025-09-29T17:20:00.000Z",
  "updateTime": "2025-09-29T17:20:00.000Z",
  "extendedData": {
    "@type": "type.googleapis.com/google.protobuf.Struct",
    "value": {
      "modelName": "face-detector",
      "modelVersion": "v1",
      "faceAnnotationGroup": {
        "faceAnnotations": [
          {
            "detectionConfidence": 0.9,
            "landmarkingConfidence": 0.8
          }
        ]
      }
    }
  }
}

依結構定義篩選物件

依物件內容鍵或特定值篩選物件。依脈絡資料篩選物件，有助於有效率地找出及管理特定物件群組。詳情請參閱「依內容篩選物件」。

在物件作業期間管理物件脈絡資料

根據預設，當您複製、重寫、組成、移動或還原物件時，Cloud Storage 會保留物件內容。

複製物件

根據預設，Cloud Storage 會在複製作業期間保留來源物件的物件內容，即使您覆寫其他中繼資料也一樣。如要在複製作業期間修改物件內容，請完成下列步驟：

指令列

根據預設，gcloud storage cp 指令、gcloud storage rsync 指令和 gcloud storage mv 指令會保留來源物件的內容。如要在這些作業期間修改情境，請使用下列任一旗標：

  • --custom-contexts 標記，可為目的地物件設定新內容。

  • --clear-custom-contexts 旗標，可防止來源物件的內容附加至目的地物件。

  • --update-custom-contexts 和 --remove-custom-contexts 旗標的組合，可在將個別內容附加至目的地物件前，修改來源物件中的個別內容。

如要在複製物件時設定新的內容，請使用 gcloud storage cp 指令：

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --custom-contexts=KEY=VALUE,...

其中：

  • SOURCE_BUCKET_NAME 是含有要複製物件的 bucket 名稱。例如：my-source-bucket。
  • SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：employees.txt。
  • DESTINATION_BUCKET_NAME 是要將物件複製到的 bucket 名稱。例如：my-destination-bucket。
  • DESTINATION_OBJECT_NAME 是目的地物件的名稱。例如：employees-backup.txt。
  • KEY 是要附加至物件的脈絡資料鍵。例如，Department。您可以指定多個以半形逗號分隔的鍵/值組合。
  • VALUE 是要與內容鍵建立關聯的值。例如：Human resources。

如要在複製物件時，從來源物件中移除所有內容，請使用 gcloud storage cp 指令：

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

其中：

  • SOURCE_BUCKET_NAME 是含有要複製物件的 bucket 名稱。例如：my-source-bucket。
  • SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：pets/dog.png。
  • DESTINATION_BUCKET_NAME 是要將物件複製到的 bucket 名稱。例如：my-destination-bucket。
  • DESTINATION_OBJECT_NAME 是目的地物件的名稱。例如：pets/cat.png。

如要在複製物件時修改來源物件中的個別內容，請使用 gcloud storage cp 指令搭配 --update-custom-contexts 和 --remove-custom-contexts：

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --update-custom-contexts=KEY=VALUE,... --remove-custom-contexts=KEY,...

其中：

  • SOURCE_BUCKET_NAME 是含有要複製物件的 bucket 名稱。例如：my-source-bucket。
  • SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：pets/dog.png。
  • DESTINATION_BUCKET_NAME 是要將物件複製到的 bucket 名稱。例如：my-destination-bucket。
  • DESTINATION_OBJECT_NAME 是目的地物件的名稱。例如：pets/cat.png。
  • KEY 是要附加至物件的脈絡資料鍵。例如，Department。您可以指定多個以半形逗號分隔的鍵/值組合或鍵。
  • VALUE 是要與情境索引鍵建立關聯的值。例如：Human resources。

JSON API

如要在複製物件時覆寫內容，請在要求主體中加入 contexts.custom 屬性：

  1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

  2. 建立 JSON 檔案，其中包含要附加至目的地物件的情境：

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

    其中：

    • KEY 是要附加至物件的脈絡資料鍵。例如：Department。
    • VALUE 是要與情境索引鍵建立關聯的值。例如：Human resources。

  3. 使用 cURL 呼叫 JSON API，並傳送 POST 物件要求：

    curl -X POST --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/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"

    其中：

    • JSON_FILE_NAME 是 JSON 檔案的路徑，其中包含物件情境資訊。
    • SOURCE_BUCKET_NAME 是 bucket 的名稱，其中包含要複製的物件。例如：my-source-bucket。
    • SOURCE_OBJECT_NAME 是要複製的物件名稱，以網址編碼。例如：employees.txt。
    • DESTINATION_BUCKET_NAME 是要複製物件的 bucket 名稱。例如：my-destination-bucket。
    • DESTINATION_OBJECT_NAME 是目的地物件的網址編碼名稱。例如：employees-backup.txt。

如要在複製作業期間捨棄來源內容，請在要求中使用 dropContextGroups=custom 查詢參數：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.s3nsapis.fr/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME?dropContextGroups=custom"

如果要求主體包含 google: 前置字元的內容，您可以保留來源物件的現有鍵和值，但 Cloud Storage 會拒絕新的 google: 鍵或修改過的值。

如要保留情境，請從要求主體中省略 contexts 屬性，並排除 dropContextGroups 查詢參數。

重寫物件

根據預設，Cloud Storage 會在重寫作業期間保留來源物件的物件內容，即使您覆寫其他中繼資料也一樣。如要在重寫作業期間修改物件內容，請完成下列步驟：

指令列

gcloud storage cp、gcloud storage rsync 和 gcloud storage mv 指令會在必要時自動執行重寫作業，例如在不同位置或儲存空間級別之間複製物件時。gcloud storage cp 和 gcloud storage rsync 會產生來源和目的地物件，而 gcloud storage mv 則會建立目的地物件並移除來源物件。由於這些作業會建立新物件，您也可以使用下列任一旗標，在同一個指令中修改或附加內容：

  • --custom-contexts 標記，用於為目的地物件設定新的結構定義。

  • --clear-custom-contexts 旗標，可防止來源物件的內容附加至目的地物件。

  • --update-custom-contexts 和 --remove-custom-contexts 旗標的組合，用於修改來源物件中的個別內容，然後再附加至目的地物件。

如要在複製物件時設定新的情境，請使用 gcloud storage cp 指令：

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --custom-contexts=KEY=VALUE,...

其中：

  • SOURCE_BUCKET_NAME 是含有要複製物件的 bucket 名稱。例如：my-source-bucket。
  • SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：employees.txt。
  • DESTINATION_BUCKET_NAME 是要將物件複製到的 bucket 名稱。例如：my-destination-bucket。
  • DESTINATION_OBJECT_NAME 是目的地物件的名稱。例如：employees-backup.txt。
  • KEY 是要附加至物件的脈絡資料鍵。例如，Department。您可以指定多個以半形逗號分隔的鍵/值組合。
  • VALUE 是要與情境索引鍵建立關聯的值。例如：Human resources。

如要在複製物件時，從來源物件中移除所有內容，請使用 gcloud storage cp 指令：

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

其中：

  • SOURCE_BUCKET_NAME 是含有要複製物件的 bucket 名稱。例如：my-source-bucket。
  • SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：pets/dog.png。
  • DESTINATION_BUCKET_NAME 是要將物件複製到的 bucket 名稱。例如：my-destination-bucket。
  • DESTINATION_OBJECT_NAME 是目的地物件的名稱。例如：pets/cat.png。

如要在複製物件時修改來源物件的個別內容，請使用 gcloud storage cp 指令搭配 --update-custom-contexts 和 --remove-custom-contexts：

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --update-custom-contexts=KEY=VALUE,... --remove-custom-contexts=KEY,...

其中：

  • SOURCE_BUCKET_NAME 是含有要複製物件的 bucket 名稱。例如：my-source-bucket。
  • SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：pets/dog.png。
  • DESTINATION_BUCKET_NAME 是要將物件複製到的 bucket 名稱。例如：my-destination-bucket。
  • DESTINATION_OBJECT_NAME 是目的地物件的名稱。例如：pets/cat.png。
  • KEY 是要附加至物件的脈絡資料鍵。例如，Department。您可以指定多個以半形逗號分隔的鍵/值組合或鍵。
  • VALUE 是要與情境索引鍵建立關聯的值。例如：Human resources。

JSON API

如要在重寫物件時覆寫內容，請在要求主體中加入 contexts.custom 屬性：

  1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

  2. 建立 JSON 檔案，內含要附加至目的地物件的內容：

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

    其中：

    • KEY 是要附加至物件的內容鍵。例如：Department。
    • VALUE 是要與內容鍵建立關聯的值。例如：Human resources。

  3. 使用 cURL 呼叫 JSON API，並傳送 POST rewrite Object 要求：

    curl -X POST --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/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"

    其中：

    • JSON_FILE_NAME 是 JSON 檔案的路徑，其中包含物件內容資訊。
    • SOURCE_BUCKET_NAME 是包含要重寫物件的 bucket 名稱。 例如：my-source-bucket。
    • SOURCE_OBJECT_NAME 是要重寫的物件名稱，須經過網址編碼。例如：employees.txt。
    • DESTINATION_BUCKET_NAME 是要重寫物件的值區名稱。例如：my-destination-bucket。
    • DESTINATION_OBJECT_NAME 是目的地物件的網址編碼名稱。 例如：employees-backup.txt。

如要在重寫作業期間捨棄來源內容，請在要求中使用 dropContextGroups=custom 查詢參數：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.s3nsapis.fr/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME?dropContextGroups=custom"

如果要求主體包含前置字串為 google: 的內容，您可以保留來源物件現有的鍵和值，但 Cloud Storage 會拒絕新的 google: 鍵或修改後的值。

如要保留情境，請從要求主體中省略 contexts 屬性，並排除 dropContextGroups 查詢參數。

Compose 物件

gcloud storage objects compose 指令和 JSON API compose 方法會合併來源物件的內容，並預設將內容附加至目的地物件。Cloud Storage 會優先處理稍後處理的來源物件，藉此解決衝突。如要進一步瞭解撰寫作業期間的物件背景資訊行為，請參閱「複合式物件背景資訊」。

指令列

如要在撰寫物件時為目的地物件指定新內容，請使用 --contexts 旗標：

gcloud storage objects compose gs://BUCKET_NAME/SOURCE_OBJECT_1 gs://BUCKET_NAME/SOURCE_OBJECT_2 gs://BUCKET_NAME/DESTINATION_OBJECT_NAME --contexts=KEY=VALUE,...

其中：

  • BUCKET_NAME 是值區名稱，其中包含來源物件，且目的地物件會建立於此。例如：my-bucket。
  • SOURCE_OBJECT_1 和 SOURCE_OBJECT_2 是要組合的來源物件。
  • DESTINATION_OBJECT_NAME 是要建立的目的地物件名稱。 例如：my-composite-object。
  • KEY 是要附加至物件的脈絡鍵。例如，Department。您可以指定多個鍵/值組合，並以半形逗號分隔。
  • VALUE 是要與情境索引鍵建立關聯的值。例如：Human resources。

如要防止來源內容附加至複合式物件，請使用 --clear-custom-contexts 旗標：

gcloud storage objects compose gs://BUCKET_NAME/SOURCE_OBJECT_1 gs://BUCKET_NAME/SOURCE_OBJECT_2 gs://BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

其中：

  • BUCKET_NAME 是包含來源物件的值區名稱，也是建立目的地物件的位置。例如：my-bucket。
  • SOURCE_OBJECT_1 和 SOURCE_OBJECT_2 是要組合的來源物件。
  • DESTINATION_OBJECT_NAME 是要建立的目的地物件名稱。例如：my-composite-object。

JSON API

如要在組合時為目的地物件指定新的情境，請在要求主體的 destination 屬性中加入情境。

  1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

  2. 建立包含要求主體的 JSON 檔案：

    {
  "sourceObjects": [
    {"name": "SOURCE_OBJECT_1"},
    {"name": "SOURCE_OBJECT_2"}
  ],
  "destination": {
    "contentType": "text/plain",
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        }
      }
    }
  }
}

    其中：

    • SOURCE_OBJECT_1 和 SOURCE_OBJECT_2 是要組合的來源物件。
    • KEY 是要附加至物件的內容鍵。例如：Department。
    • VALUE 是要與情境索引鍵建立關聯的值。例如：Human resources。

  3. 使用 cURL 呼叫 JSON API，並傳送 POST compose 物件要求：

    curl -X POST --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/DESTINATION_OBJECT_NAME/compose"

    其中：

    • JSON_FILE_NAME 是包含要求主體的 JSON 檔案路徑。
    • BUCKET_NAME 是值區名稱，其中包含來源物件，且目的地物件會建立於此。例如：my-bucket。
    • DESTINATION_OBJECT_NAME 是要建立的目的地物件名稱。例如：my-composite-object。

如要避免來源內容附加至複合式物件，請在要求中使用 dropContextGroups=custom 查詢參數：

  1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

  2. 建立包含要求主體的 JSON 檔案：

    {
  "sourceObjects": [
    {"name": "SOURCE_OBJECT_1"},
    {"name": "SOURCE_OBJECT_2"}
  ],
  "destination": {
    "contentType": "text/plain"
}
}

    其中：

    • SOURCE_OBJECT_1 和 SOURCE_OBJECT_2 是要組合的來源物件。

  3. 使用 cURL 呼叫 JSON API，並傳送 POST compose 物件要求：

    curl -X POST --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/DESTINATION_OBJECT_NAME/compose?dropContextGroups=custom"

    其中：

    • JSON_FILE_NAME 是包含要求主體的 JSON 檔案路徑。
    • BUCKET_NAME 是包含來源物件，且目的地物件建立位置的 bucket 名稱。例如：my-bucket。
    • DESTINATION_OBJECT_NAME 是要建立的目的地物件名稱。例如：my-composite-object。

大量管理物件情境

如要透過單一工作管理數百萬或數十億個物件的物件內容，請使用 儲存空間批次作業。如要建立工作，請提供資訊清單檔案或使用物件前置字串，指定目標物件。指定物件後，建立批次作業工作，更新物件內容。

在 BigQuery 中分析物件內容

如果您有有效的 Storage Intelligence 訂閱方案，可以在 BigQuery 中查詢及分析物件內容。使用物件內容目錄檢視 (object_contexts_catalog_view) 查詢內容鍵、值和結構化 extendedData 酬載 (例如圖片標籤、偵測到的臉部和定界框)。目錄檢視畫面每 24 小時更新一次。

舉例來說，如要找出特定註解分數超過門檻的所有物件：

SELECT
  t.project,
  t.bucket,
  t.name,
  t.generation,
  label
FROM
  `PROJECT_ID.INSIGHTS_DATASET.object_contexts_catalog_view` AS t,
  UNNEST(t.contexts) AS context,
  UNNEST(JSON_QUERY_ARRAY(context.extendedData.labelAnnotationGroup.labelAnnotations)) AS label
WHERE
  context.key = "google:annotation:label-detector-v1"
  AND FLOAT64(label.score) > 0.75;

更改項目：

  • PROJECT_ID：包含儲存空間分析資料集的專案 ID。
  • INSIGHTS_DATASET：儲存空間分析資料集的名稱。

如要進一步瞭解目錄檢視結構定義，請參閱「物件脈絡資料目錄結構定義」。如需更多查詢範例，請參閱「分析物件脈絡資料」。

後續步驟