Objek Penyusunan

Ringkasan

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-hal berikut saat menulis objek:

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

• Karena kelas penyimpanan lain dikenai biaya penghapusan awal, Anda harus selalu menggunakan Penyimpanan standar untuk objek sementara.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menulis objek, minta administrator untuk memberi Anda peran IAM Storage Object User (roles/storage.objectUser) di bucket. Peran yang telah ditentukan ini berisi izin yang diperlukan untuk menyusun objek. Untuk melihat izin persis yang diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

• storage.objects.create
• storage.objects.delete
  • Izin ini hanya diperlukan jika ingin memberi objek yang Anda tulis 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 awalan umum tanpa harus mencantumkan setiap objek secara terpisah dalam perintah Google Cloud CLI.

Jika ingin menetapkan konfigurasi retensi untuk objek yang Anda tulis, Anda juga memerlukan izin storage.objects.setRetention. Untuk mendapatkan izin ini, minta administrator 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 bawaan atau peran khusus lainnya.

Untuk mengetahui informasi tentang cara memberikan peran pada bucket, lihat Menggunakan IAM dengan 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.

Catatan: Anda juga dapat menggunakan karakter pengganti untuk membuat objek dengan imbuhan umum tanpa harus mencantumkan setiap objek secara terpisah di perintah.

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, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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, lihatDokumentasi referensi Cloud Storage C# API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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, lihatDokumentasi referensi Cloud Storage Go API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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, lihatDokumentasi referensi Cloud Storage Java API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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, lihatDokumentasi referensi Cloud Storage Node.js API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

/**
 * 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, lihatDokumentasi referensi Cloud Storage PHP API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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, lihatDokumentasi referensi Cloud Storage Python API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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, lihatDokumentasi referensi Cloud Storage Ruby API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

REST API

JSON API

1. Telah menginstal dan melakukan inisialisasigcloud CLI, agar dapat membuat token akses untuk header Authorization.

   Atau, Anda dapat membuat token akses menggunakan OAuth 2.0 Playground dan menyertakannya di header Authorization.

2. 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 dari objek gabungan yang dihasilkan.

3. 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

1. Telah menginstal dan melakukan inisialisasigcloud CLI, agar dapat membuat token akses untuk header Authorization.

   Atau, Anda dapat membuat token akses menggunakan OAuth 2.0 Playground dan menyertakannya di header Authorization.

2. 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.

3. Gunakan cURL untuk memanggil XML API dengan permintaan Objek PUT dan 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 dari 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.

Catatan: XML API mendukung penyertaan nomor pembuatan untuk setiap <Component>, menggunakan elemen <Generation> atau elemen <IfGenerationMatch>.

Langkah selanjutnya

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