使用物件內容

本頁說明如何以鍵/值配對的形式，在 Cloud Storage 物件上附加及管理內容。

取得必要角色

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

使用環境建立物件： Storage 物件建立者 (roles/storage.objectCreator)
從物件附加、更新、查看及刪除結構定義： Storage 物件使用者 (roles/storage.objectUser)
查看附加至物件的脈絡資料鍵和值： Storage 物件檢視者 (roles/storage.objectViewer)
在重寫、複製及組合作業期間捨棄物件內容： Storage 舊版物件擁有者 (roles/storage.legacyObjectOwner)

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

這些預先定義的角色具備建立及管理物件內容所需的權限。如要查看確切的必要權限，請展開「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

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

將背景資訊附加至新物件

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

指令列

如要使用 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 是您要向其上傳物件的值區名稱。例如：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 中的現有物件。

指令列

使用 gcloud storage objects update 指令：

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

其中：

BUCKET_NAME 是值區名稱，其中包含您要編輯內容的物件。例如：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 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。


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

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

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

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

查看物件脈絡

您可以列出物件中繼資料或說明特定物件，藉此查看物件的脈絡資料。

指令列

使用 gcloud storage objects describe 指令：

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME

其中：

BUCKET_NAME 是值區名稱，其中包含您要查看內容的物件。例如：my-bucket。
OBJECT_NAME 是您要查看內容的物件名稱。例如：employees.txt

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

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: Human resources
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

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

使用 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 是您要查看內容的物件名稱，並經過網址編碼。例如：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"
        }
      }
    }
  }

依據脈絡篩選物件

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

在物件作業期間管理物件內容

根據預設，複製、重寫、組合、移動或還原物件時，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 是包含要複製物件的值區名稱。例如：my-source-bucket。
SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：employees.txt。
DESTINATION_BUCKET_NAME 是要將物件複製到的值區名稱。例如：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 是包含要複製物件的值區名稱。例如：my-source-bucket。
SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：pets/dog.png。
DESTINATION_BUCKET_NAME 是要將物件複製到的值區名稱。例如：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 是包含要複製物件的值區名稱。例如：my-source-bucket。
SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：pets/dog.png。
DESTINATION_BUCKET_NAME 是要將物件複製到的值區名稱。例如：my-destination-bucket。
DESTINATION_OBJECT_NAME 是目標物件的名稱。例如：pets/cat.png。
KEY 是要附加至物件的內容鍵。例如，Department。您可以指定多個以半形逗號分隔的鍵/值組合或鍵。
VALUE 是要與內容鍵建立關聯的值。例如：Human resources。

JSON API

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

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

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

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

其中：

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

使用 cURL 透過 POST 物件要求呼叫 JSON API：
```
curl -X POST --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/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"
```
其中：
- JSON_FILE_NAME 是包含物件內容資訊的 JSON 檔案路徑。
- SOURCE_BUCKET_NAME 是包含要複製物件的值區名稱。例如：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.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME?dropContextGroups=custom"

如要保留內容，請從要求主體中省略 contexts.custom 屬性，並在查詢參數中排除 dropContextGroups=custom：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"

如要瞭解內容在複製作業期間的行為，請參閱 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 是包含要複製物件的值區名稱。例如：my-source-bucket。
SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：employees.txt。
DESTINATION_BUCKET_NAME 是要將物件複製到的值區名稱。例如：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 是包含要複製物件的值區名稱。例如：my-source-bucket。
SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：pets/dog.png。
DESTINATION_BUCKET_NAME 是要將物件複製到的值區名稱。例如：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 是包含要複製物件的值區名稱。例如：my-source-bucket。
SOURCE_OBJECT_NAME 是要複製的物件名稱。例如：pets/dog.png。
DESTINATION_BUCKET_NAME 是要將物件複製到的值區名稱。例如：my-destination-bucket。
DESTINATION_OBJECT_NAME 是目標物件的名稱。例如：pets/cat.png。
KEY 是要附加至物件的內容鍵。例如，Department。您可以指定多個以半形逗號分隔的鍵/值組合或鍵。
VALUE 是要與內容鍵建立關聯的值。例如：Human resources。

JSON API

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

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

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

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

其中：

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

使用 cURL 透過 POST 重寫物件要求呼叫 JSON API：
```
curl -X POST --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/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"
```
其中：
- JSON_FILE_NAME 是包含物件內容資訊的 JSON 檔案路徑。
- SOURCE_BUCKET_NAME 是包含要重寫物件的值區名稱。例如：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.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME?dropContextGroups=custom"

如要保留內容，請從要求主體中省略 contexts.custom 屬性，並在查詢參數中排除 dropContextGroups=custom：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"

如要瞭解在重寫作業期間，內容的行為方式，請參閱dropContextGroups查詢參數。

撰寫物件

gcloud storage objects compose 指令和 JSON API 組合方法會合併來源物件的內容，並預設將內容附加至目標物件。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 屬性中加入環境。

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

建立包含要求內文的 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。

使用 cURL 透過 POST 組合物件要求呼叫 JSON API：
```
curl -X POST --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/DESTINATION_OBJECT_NAME/compose"
```
其中：
- JSON_FILE_NAME 是包含要求主體的 JSON 檔案路徑。
- BUCKET_NAME 是包含來源物件的值區名稱，也是要建立目的地物件的位置。例如：my-bucket。
- DESTINATION_OBJECT_NAME 是要建立的目標物件名稱。例如：my-composite-object。

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

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

建立包含要求內文的 JSON 檔案：

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

其中：

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

使用 cURL 透過 POST 組合物件要求呼叫 JSON API：
```
curl -X POST --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/DESTINATION_OBJECT_NAME/compose?dropContextGroups=custom"
```
其中：
- JSON_FILE_NAME 是包含要求主體的 JSON 檔案路徑。
- BUCKET_NAME 是包含來源物件的值區名稱，也是要建立目的地物件的位置。例如：my-bucket。
- DESTINATION_OBJECT_NAME 是要建立的目標物件名稱。例如：my-composite-object。

後續步驟

如要瞭解物件內容屬性，請參閱 Cloud Storage API 說明文件。

使用物件內容 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

取得必要角色

所需權限

將背景資訊附加至新物件

指令列

JSON API

為現有物件附加或修改背景資訊

指令列

用戶端程式庫

Java

JSON API

查看物件脈絡

指令列

用戶端程式庫

Java

JSON API

依據脈絡篩選物件

在物件作業期間管理物件內容

複製物件

指令列

JSON API

重寫物件

指令列

JSON API

撰寫物件

指令列

JSON API

後續步驟

使用物件內容