Menyusun objek

Halaman ini menunjukkan cara menyusun objek Cloud Storage menjadi satu objek. Permintaan penyusunan membutuhkan antara 1 hingga 32 objek dan membuat objek gabungan baru. Objek gabungan adalah penyambungan objek sumber sesuai urutan yang ditentukan dalam permintaan.

Perhatikan hal berikut saat menyusun objek:

Objek sumber tidak terpengaruh oleh proses penyusunan. Jika dimaksudkan untuk bersifat sementara, Anda harus menghapusnya setelah berhasil menyelesaikan penyusunan.

Karena kelas penyimpanan lainnya dikenai biaya penghapusan awal, Anda harus selalu menggunakan Standard Storage untuk objek sementara.

Peran yang diperlukan

Jika ingin mendapatkan izin yang diperlukan untuk menyusun objek, minta administrator untuk memberi Anda peran IAM Storage Object User (roles/storage.objectUser) di bucket. Peran bawaan ini berisi izin yang diperlukan untuk menyusun objek. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

storage.objects.create
storage.objects.delete
- Izin ini hanya diperlukan jika Anda ingin memberi objek yang Anda susun nama yang sama dengan objek yang sudah ada di bucket.
storage.objects.get
storage.objects.list
- Izin ini hanya diperlukan jika Anda ingin menggunakan karakter pengganti untuk menyusun objek dengan imbuhan umum tanpa harus mencantumkan setiap objek secara terpisah dalam perintah Google Cloud CLI.

Jika ingin menetapkan konfigurasi retensi untuk objek yang Anda susun, Anda juga memerlukan izin storage.objects.setRetention. Untuk mendapatkan izin ini, minta administrator Anda untuk memberi Anda peran Storage Object Admin (roles/storage.objectAdmin), bukan peran Storage Object User (roles/storage.objectUser).

Anda juga bisa mendapatkan izin ini dengan peran standar atau peran khusus lainnya.

Untuk mengetahui informasi tentang cara memberikan peran di bucket, lihat Menetapkan dan mengelola kebijakan IAM di bucket.

Membuat objek gabungan

Command line

Gunakan perintah 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

Dengan keterangan:

BUCKET_NAME adalah nama bucket yang berisi objek sumber.
SOURCE_OBJECT_1 dan SOURCE_OBJECT_2 adalah nama objek sumber yang akan digunakan dalam penyusunan objek.
COMPOSITE_OBJECT_NAME adalah nama yang Anda berikan ke hasil penyusunan objek.

Library klien

C++

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage C++ API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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#

Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Cloud Storage C# API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.


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

public class ComposeObjectSample
{
    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")
    {
        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
        {
            SourceObjects = sourceObjects,
            Destination = new Google.Apis.Storage.v1.Data.Object { ContentType = "text/plain" }
        }, bucketName, targetObjectName).Execute();

        Console.WriteLine($"New composite file {targetObjectName} was created in bucket {bucketName}" +
            $" by combining {firstObjectName} and {secondObjectName}.");
    }
}

Go

Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi Cloud Storage Go API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihat Cloud Storage Java API dokumentasi referensi.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihat Cloud Storage Node.js API dokumentasi referensi.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

/**
 * 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

Untuk mengetahui informasi selengkapnya, lihat Cloud Storage PHP API dokumentasi referensi.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihat Cloud Storage Python API dokumentasi referensi.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Untuk mengetahui informasi selengkapnya, lihat Cloud Storage Ruby API dokumentasi referensi.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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
        .send()
        .await?;
    println!(
        "successfully composed {COMPOSE_SOURCE_1} and {COMPOSE_SOURCE_2} into object {object:?}"
    );
    Ok(())
}

REST API

JSON API

Instal dan lakukan inisialisasi gcloud CLI yang terinstal dan terinisialisasi , yang memungkinkan Anda membuat token akses untuk header Authorization.

Buat file JSON yang berisi informasi berikut:

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

Dengan keterangan:

SOURCE_OBJECT_1 dan SOURCE_OBJECT_2 adalah nama objek sumber yang akan digunakan dalam penyusunan objek.

COMPOSITE_OBJECT_CONTENT_TYPE adalah Content-Type objek gabungan yang dihasilkan.

Gunakan cURL untuk memanggil JSON API dengan permintaan Objek POST:
```
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"
```
Dengan keterangan:
- JSON_FILE_NAME adalah nama file yang Anda buat di langkah sebelumnya.
- BUCKET_NAME adalah nama bucket yang berisi objek sumber.
- COMPOSITE_OBJECT_NAME adalah nama yang Anda berikan ke hasil penyusunan objek.

Jika berhasil, responsnya adalah resource objek untuk objek gabungan yang dihasilkan.

XML API

Instal dan lakukan inisialisasi gcloud CLI yang terinstal dan terinisialisasi , yang memungkinkan Anda membuat token akses untuk header Authorization.

Buat file XML yang berisi informasi berikut:

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

Dengan keterangan:

SOURCE_OBJECT_1 dan SOURCE_OBJECT_2 adalah nama objek sumber yang akan digunakan dalam penyusunan objek.

Gunakan cURL untuk memanggil XML API dengan permintaan Objek PUT yang menyertakan parameter string kueri compose:
```
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"
```
Dengan keterangan:
- XML_FILE_NAME adalah nama file yang Anda buat di langkah sebelumnya.
- COMPOSITE_OBJECT_CONTENT_TYPE adalah Content-Type objek gabungan yang dihasilkan.
- BUCKET_NAME adalah nama bucket yang berisi objek sumber.
- COMPOSITE_OBJECT_NAME adalah nama yang Anda berikan ke hasil penyusunan objek.

Jika berhasil, isi respons kosong akan ditampilkan.

Langkah berikutnya

Pelajari penyusunan objek lebih lanjut.
Pelajari cara menggunakan prasyarat permintaan untuk mencegah kondisi race.

Kecuali dinyatakan lain, konten di halaman ini dilisensikan berdasarkan Lisensi Creative Commons Attribution 4.0, sedangkan contoh kode dilisensikan berdasarkan Lisensi Apache 2.0. Untuk mengetahui informasi selengkapnya, lihat Kebijakan Situs Google Developers. Java adalah merek dagang terdaftar dari Oracle dan/atau afiliasinya.

Terakhir diperbarui pada 2026-05-03 UTC.