撰寫物件

總覽

本頁說明如何將多個 Cloud Storage 物件組合成單一物件。組合要求會採用 1 到 32 個物件，並建立新的複合物件。複合物件是來源物件的串連，順序與要求中指定的順序相同。

除非您決定在組合處理期間刪除來源物件，否則來源物件不會受到影響。

臨時物件的費用注意事項

如果來源物件是暫時性的，請在組合物件時注意下列費用考量：

• 視儲存空間級別而定，來源物件須符合最短儲存時間規定，否則可能會產生提前刪除費用。

• 如果啟用虛刪除或物件版本管理功能，在組合完成後刪除來源物件，可能會導致來源物件遭到虛刪除或成為非目前版本，進而產生額外的儲存空間費用。

• 如要盡量減少臨時物件的費用，請在組合程序中使用 deleteSourceObjects 選項，硬性刪除臨時物件。使用這個選項刪除的物件不會產生提前刪除費用。此外，使用這個選項刪除的物件不會透過虛刪除或物件版本管理功能保留，因為資料會保留在複合物件中。

必要的角色

如要取得組合物件所需的權限，請要求管理員授予您 bucket 的「Storage 物件使用者」(roles/storage.objectUser) IAM 角色。這個預先定義的角色具備撰寫物件所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

• storage.objects.create
• storage.objects.delete
  • 只有在您想將組合的物件命名為與值區中現有物件相同的名稱時，才需要這項權限。
• storage.objects.get
• storage.objects.list
  • 如果您想使用萬用字元組成具有相同前置字元的物件，而不必在 Google Cloud CLI 指令中個別列出每個物件，則需要此權限。

如要為撰寫的物件設定保留設定，您也需要 storage.objects.setRetention 權限。如要取得這項權限，請要求管理員授予您「Storage 物件管理員」(roles/storage.objectAdmin) 角色，而非「Storage 物件使用者」(roles/storage.objectUser) 角色。

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

如要瞭解如何授予值區角色，請參閱「設定及管理值區的 IAM 政策」。

建立複合物件

指令列

使用 gcloud storage objects compose 指令：

gcloud storage objects compose \
    gs://BUCKET_NAME/SOURCE_OBJECT_1 gs://BUCKET_NAME/SOURCE_OBJECT_2 \
    gs://BUCKET_NAME/COMPOSITE_OBJECT_NAME

其中：

• BUCKET_NAME 是包含來源物件的值區名稱。
• SOURCE_OBJECT_1 和 SOURCE_OBJECT_2 是要在物件組合中使用的來源物件名稱。
• COMPOSITE_OBJECT_NAME 是您要為物件組合結果指定的名稱。

如要在合成過程中刪除來源物件，請在先前的指令中加入 --delete-source-objects 標記。

注意： 您也可以使用萬用字元組合具有共同前置字串的物件，而不必在指令中分別列出每個物件。

用戶端程式庫

C++

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

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

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& destination_object_name,
   std::vector<gcs::ComposeSourceObject> const& compose_objects) {
  StatusOr<gcs::ObjectMetadata> composed_object = client.ComposeObject(
      bucket_name, compose_objects, destination_object_name);
  if (!composed_object) throw std::move(composed_object).status();

  std::cout << "Composed new object " << composed_object->name()
            << " in bucket " << composed_object->bucket()
            << "\nFull metadata: " << *composed_object << "\n";
}

C#

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

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

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class ComposeObjectSample
{
    /// <summary>
    /// Combines multiple source objects into a single target object within a specified bucket,
    /// with the option to delete the original source objects upon successful composition.
    /// </summary>
    /// <param name="bucketName">The name of the bucket containing the source objects.</param>
    /// <param name="firstObjectName">The name of the first source object to be composed.</param>
    /// <param name="secondObjectName">The name of the second source object to be composed.</param>
    /// <param name="targetObjectName">The name for the newly created composite object.</param>
    /// <param name="deleteSourceObjects">If set to <c>true</c>, the method will automatically delete <paramref name="firstObjectName"/> and <paramref name="secondObjectName"/> upon successful composition.
    /// Defaults to <c>false</c>.</param>
    public void ComposeObject(
        string bucketName = "your-bucket-name",
        string firstObjectName = "your-first-object-name",
        string secondObjectName = "your-second-object-name",
        string targetObjectName = "new-composite-object-name",
        bool deleteSourceObjects = false)
    {
        var storage = StorageClient.Create();

        var sourceObjects = new List<ComposeRequest.SourceObjectsData>
        {
            new ComposeRequest.SourceObjectsData { Name = firstObjectName },
            new ComposeRequest.SourceObjectsData { Name = secondObjectName }
        };
        //You could add as many sourceObjects as you want here, up to the max of 32.

        storage.Service.Objects.Compose(new ComposeRequest
        {
            DeleteSourceObjects = deleteSourceObjects,
            SourceObjects = sourceObjects,
            Destination = new Google.Apis.Storage.v1.Data.Object { ContentType = "text/plain" }
        }, bucketName, targetObjectName).Execute();

        string deletionMessage = deleteSourceObjects ? " and the source objects were deleted." : ".";
        Console.WriteLine($"New composite file {targetObjectName} was created in bucket {bucketName}" +
            $" by combining {firstObjectName} and {secondObjectName}{deletionMessage}");
    }
}

Go

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

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

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// composeFile composes source objects to create a composite object.
func composeFile(w io.Writer, bucket, object1, object2, toObject string) error {
	// bucket := "bucket-name"
	// object1 := "object-name-1"
	// object2 := "object-name-2"
	// toObject := "object-name-3"

	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	src1 := client.Bucket(bucket).Object(object1)
	src2 := client.Bucket(bucket).Object(object2)
	dst := client.Bucket(bucket).Object(toObject)

	// ComposerFrom takes varargs, so you can put as many objects here
	// as you want.
	_, err = dst.ComposerFrom(src1, src2).Run(ctx)
	if err != nil {
		return fmt.Errorf("ComposerFrom: %w", err)
	}
	fmt.Fprintf(w, "New composite object %v was created by combining %v and %v\n", toObject, object1, object2)
	return nil
}

Java

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

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

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class ComposeObject {
  public static void composeObject(
      String bucketName,
      String firstObjectName,
      String secondObjectName,
      String targetObjectName,
      String projectId) {
    // 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 the first GCS object to compose
    // String firstObjectName = "your-first-object-name";

    // The ID of the second GCS object to compose
    // String secondObjectName = "your-second-object-name";

    // The ID to give the new composite object
    // String targetObjectName = "new-composite-object-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    // Optional: set a generation-match precondition to avoid potential race
    // conditions and data corruptions. The request returns a 412 error if the
    // preconditions are not met.
    Storage.BlobTargetOption precondition;
    if (storage.get(bucketName, targetObjectName) == null) {
      // For a target object that does not yet exist, set the DoesNotExist precondition.
      // This will cause the request to fail if the object is created before the request runs.
      precondition = Storage.BlobTargetOption.doesNotExist();
    } else {
      // If the destination already exists in your bucket, instead set a generation-match
      // precondition. This will cause the request to fail if the existing object's generation
      // changes before the request runs.
      precondition =
          Storage.BlobTargetOption.generationMatch(
              storage.get(bucketName, targetObjectName).getGeneration());
    }

    Storage.ComposeRequest composeRequest =
        Storage.ComposeRequest.newBuilder()
            // addSource takes varargs, so you can put as many objects here as you want, up to the
            // max of 32
            .addSource(firstObjectName, secondObjectName)
            .setTarget(BlobInfo.newBuilder(bucketName, targetObjectName).build())
            .setTargetOptions(precondition)
            .build();

    Blob compositeObject = storage.compose(composeRequest);

    System.out.println(
        "New composite object "
            + compositeObject.getName()
            + " was created by combining "
            + firstObjectName
            + " and "
            + secondObjectName);
  }
}

Node.js

詳情請參閱「Cloud Storage Node.js API 參考文件」。

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

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of the first GCS file to compose
// const firstFileName = 'your-first-file-name';

// The ID of the second GCS file to compose
// const secondFileName = 'your-second-file-name';

// The ID to give the new composite file
// const destinationFileName = 'new-composite-file-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function composeFile() {
  const bucket = storage.bucket(bucketName);
  const sources = [firstFileName, secondFileName];

  // Optional:
  // Set a generation-match precondition to avoid potential race conditions
  // and data corruptions. The request to compose is aborted if the object's
  // generation number does not match your precondition. For a destination
  // object that does not yet exist, set the ifGenerationMatch precondition to 0
  // If the destination object already exists in your bucket, set instead a
  // generation-match precondition using its generation number.
  const combineOptions = {
    ifGenerationMatch: destinationGenerationMatchPrecondition,
  };
  await bucket.combine(sources, destinationFileName, combineOptions);

  console.log(
    `New composite file ${destinationFileName} was created by combining ${firstFileName} and ${secondFileName}`
  );
}

composeFile().catch(console.error);

PHP

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

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

use Google\Cloud\Storage\StorageClient;

/**
 * Compose two objects into a single target object.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $firstObjectName The name of the first GCS object to compose.
 *        (e.g. 'my-object-1')
 * @param string $secondObjectName The name of the second GCS object to compose.
 *        (e.g. 'my-object-2')
 * @param string $targetObjectName The name of the object to be created.
 *        (e.g. 'composed-my-object-1-my-object-2')
 */
function compose_file(string $bucketName, string $firstObjectName, string $secondObjectName, string $targetObjectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    // In this example, we are composing only two objects, but Cloud Storage supports
    // composition of up to 32 objects.
    $objectsToCompose = [$firstObjectName, $secondObjectName];

    $targetObject = $bucket->compose($objectsToCompose, $targetObjectName, [
        'destination' => [
            'contentType' => 'application/octet-stream'
        ]
    ]);

    if ($targetObject->exists()) {
        printf(
            'New composite object %s was created by combining %s and %s',
            $targetObject->name(),
            $firstObjectName,
            $secondObjectName
        );
    }
}

Python

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

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

from google.cloud import storage


def compose_file(bucket_name, first_blob_name, second_blob_name, destination_blob_name):
    """Concatenate source blobs into destination blob."""
    # bucket_name = "your-bucket-name"
    # first_blob_name = "first-object-name"
    # second_blob_name = "second-blob-name"
    # destination_blob_name = "destination-object-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    destination = bucket.blob(destination_blob_name)
    destination.content_type = "text/plain"

    # Note sources is a list of Blob instances, up to the max of 32 instances per request
    sources = [bucket.blob(first_blob_name), bucket.blob(second_blob_name)]

    # Optional: set a generation-match precondition to avoid potential race conditions
    # and data corruptions. The request to compose is aborted if the object's
    # generation number does not match your precondition. For a destination
    # object that does not yet exist, set the if_generation_match precondition to 0.
    # If the destination object already exists in your bucket, set instead a
    # generation-match precondition using its generation number.
    # There is also an `if_source_generation_match` parameter, which is not used in this example.
    destination_generation_match_precondition = 0

    destination.compose(sources, if_generation_match=destination_generation_match_precondition)

    print(
        "New composite object {} in the bucket {} was created by combining {} and {}".format(
            destination_blob_name, bucket_name, first_blob_name, second_blob_name
        )
    )
    return destination

Ruby

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

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

def compose_file bucket_name:, first_file_name:, second_file_name:, destination_file_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of the first GCS object to compose
  # first_file_name = "your-first-file-name"

  # The ID of the second GCS object to compose
  # second_file_name = "your-second-file-name"

  # The ID to give the new composite object
  # destination_file_name = "new-composite-file-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket = storage.bucket bucket_name, skip_lookup: true

  destination = bucket.compose [first_file_name, second_file_name], destination_file_name do |f|
    f.content_type = "text/plain"
  end

  puts "Composed new file #{destination.name} in the bucket #{bucket_name} " \
       "by combining #{first_file_name} and #{second_file_name}"
end

Rust

use google_cloud_storage::client::StorageControl;
use google_cloud_storage::model::{Object, compose_object_request::SourceObject};

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const COMPOSE_SOURCE_1: &str = "compose-source-object-1";
    const COMPOSE_SOURCE_2: &str = "compose-source-object-2";
    const DESTINATION_NAME: &str = "compose-destination-object";
    let object = client
        .compose_object()
        .set_destination(
            Object::new()
                .set_bucket(format!("projects/_/buckets/{bucket_id}"))
                .set_name(DESTINATION_NAME),
        )
        .set_source_objects([
            SourceObject::new().set_name(COMPOSE_SOURCE_1),
            SourceObject::new().set_name(COMPOSE_SOURCE_2),
        ])
        // Consider .set_generation() to make request idempotent
        // Consider .set_delete_source_objects() to automatically delete the source objects
        .send()
        .await?;
    println!(
        "successfully composed {COMPOSE_SOURCE_1} and {COMPOSE_SOURCE_2} into object {object:?}"
    );
    Ok(())
}

REST API

JSON API

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

2. 建立包含下列資訊的 JSON 檔案：

   {
     "sourceObjects": [
       {
         "name": "SOURCE_OBJECT_1"
       },
       {
         "name": "SOURCE_OBJECT_2"
       }
     ],
     "destination": {
       "contentType": "COMPOSITE_OBJECT_CONTENT_TYPE"
     },
     "deleteSourceObjects": DELETE_SOURCE_OBJECTS_BOOLEAN
   }

   其中：

   • SOURCE_OBJECT_1 和 SOURCE_OBJECT_2 是要在物件組合中使用的來源物件名稱。
   • COMPOSITE_OBJECT_CONTENT_TYPE 是產生的複合物件的 Content-Type。
   • 如要在組合處理程序中刪除來源物件，請將 DELETE_SOURCE_OBJECTS_BOOLEAN 設為 true；如要保留來源物件，請將 DELETE_SOURCE_OBJECTS_BOOLEAN 設為 false。預設值為 false。

3. 使用 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/COMPOSITE_OBJECT_NAME/compose"

   其中：

   • JSON_FILE_NAME 是您在上一個步驟中建立的檔案名稱。
   • BUCKET_NAME 是包含來源物件的值區名稱。
   • COMPOSITE_OBJECT_NAME 是您要為物件組合結果指定的名稱。

如果成功，回應會是結果複合物件的物件資源。

XML API

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

2. 建立包含下列資訊的 XML 檔案：

     <ComposeRequest>
       <Component>
         <Name>SOURCE_OBJECT_1</Name>
       </Component>
       <Component>
         <Name>SOURCE_OBJECT_2</Name>
       </Component>
     </ComposeRequest>

   其中：

   • SOURCE_OBJECT_1 和 SOURCE_OBJECT_2 是要在物件組合中使用的來源物件名稱。

3. 使用 cURL 透過包含 compose 查詢字串參數的 PUT 物件要求呼叫 XML API：

   curl -X PUT --data-binary @XML_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: COMPOSITE_OBJECT_CONTENT_TYPE" \
     "https://storage.googleapis.com/BUCKET_NAME/COMPOSITE_OBJECT_NAME?compose"

   其中：

   • XML_FILE_NAME 是您在前一個步驟建立的檔案名稱。
   • COMPOSITE_OBJECT_CONTENT_TYPE 是產生的複合物件的 Content-Type。
   • BUCKET_NAME 是包含來源物件的值區名稱。
   • COMPOSITE_OBJECT_NAME 是您要為物件組合結果指定的名稱。

如果成功，系統會傳回空白的回應主體。

注意： XML API 支援為每個 <Component> 加入代號，方法是使用 <Generation> 元素或 <IfGenerationMatch> 元素。

後續步驟

• 進一步瞭解物件組合。
• 瞭解如何使用要求前提條件來避免競爭狀況。