Objekte zusammensetzen

Übersicht

Auf dieser Seite erfahren Sie, wie Sie mehrere Cloud Storage-Objekte in einem einzelnen Objekt zusammenfassen. Eine Compose-Anfrage umfasst zwischen 1 und 32 Objekte und erstellt ein neues zusammengesetztes Objekt. Das zusammengesetzte Objekt ist eine Verkettung der Quellobjekte in der Reihenfolge, in der sie in der Anfrage angegeben wurden.

Die Quellobjekte sind nicht betroffen, es sei denn, Sie löschen sie während des Zusammensetzungsprozesses.

Kosten für temporäre Objekte

Wenn die Quellobjekte temporär sein sollen, beachten Sie beim Zusammensetzen von Objekten die folgenden Kostenaspekte:

  • Für Quellobjekte gelten je nach Speicherklasse Mindestspeicherdauern. Möglicherweise fallen Gebühren für vorzeitiges Löschen an.

  • Wenn vorläufiges Löschen oder Objektversionsverwaltung aktiviert ist, kann das Löschen der Quellobjekte nach Abschluss der Zusammensetzung dazu führen, dass die Quellobjekte vorläufig gelöscht oder nicht aktuell werden. Dies kann zusätzliche Speicherkosten verursachen.

  • Um die Abrechnung für temporäre Objekte zu minimieren, sollten Sie die temporären Objekte während des Zusammensetzungsvorgangs mit der Option deleteSourceObjects endgültig löschen. Für Objekte, die mit dieser Option gelöscht werden, fallen keine Gebühren für die vorzeitige Löschung an. Außerdem werden Objekte, die mit dieser Option gelöscht werden, nicht durch vorläufiges Löschen oder die Objektversionsverwaltung beibehalten, da die Daten im zusammengesetzten Objekt beibehalten werden.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Storage-Objekt-Nutzer (roles/storage.objectUser) für den Bucket zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Zusammensetzen von Objekten benötigen. Diese vordefinierte Rolle enthält die Berechtigungen, die zum Zusammensetzen von Objekten erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

  • storage.objects.create
  • storage.objects.delete
    • Diese Berechtigung ist nur erforderlich, wenn Sie dem erstellten Objekt den gleichen Namen wie einem Objekt geben möchten, das bereits im Bucket vorhanden ist.
  • storage.objects.get
  • storage.objects.list
    • Diese Berechtigung ist nur erforderlich, wenn Sie Platzhalter verwenden möchten, um Objekte mit einem gemeinsamen Präfix zusammenzusetzen, ohne jedes Objekt einzeln in Ihrem Google Cloud CLI-Befehl auflisten zu müssen.

Wenn Sie eine Aufbewahrungskonfiguration für das Objekt festlegen möchten, das Sie erstellen, benötigen Sie auch die Berechtigung storage.objects.setRetention. Bitten Sie den Administrator, Ihnen die Rolle „Storage-Objekt-Administrator“ (roles/storage.objectAdmin) anstelle der Rolle „Storage-Objekt-Nutzer“ (roles/storage.objectUser) zuzuweisen, um diese Berechtigung zu erhalten.

Sie können diese Berechtigungen auch mit anderen vordefinierten Rollen oder benutzerdefinierten Rollen erhalten.

Informationen zum Zuweisen von Rollen für Buckets finden Sie unter IAM-Richtlinien für Buckets festlegen und verwalten.

Zusammengesetztes Objekt erstellen

Befehlszeile

Führen Sie den Befehl gcloud storage objects compose aus:

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

Dabei gilt:

  • BUCKET_NAME ist der Name des Buckets, der die Quellobjekte enthält.
  • SOURCE_OBJECT_1 und SOURCE_OBJECT_2 sind die Namen der Quellobjekte, die bei der Objektzusammensetzung verwendet werden sollen.
  • COMPOSITE_OBJECT_NAME ist der Name, den Sie dem Ergebnis der Objektzusammensetzung geben.

Wenn Sie die Quellobjekte im Rahmen des Kompositionsprozesses löschen möchten, fügen Sie dem vorherigen Befehl das Flag --delete-source-objects hinzu.

Clientbibliotheken

C++

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage C++ API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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,
   bool delete_source_objects) {
  StatusOr<gcs::ObjectMetadata> composed_object = client.ComposeObject(
      bucket_name, compose_objects, destination_object_name,
      gcs::DeleteSourceObjects(delete_source_objects));
  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";
  if (delete_source_objects) {
    std::cout << "The source objects were deleted.\n";
  }
}

C#

Weitere Informationen finden Sie in der API-Referenzdokumentation zu Cloud Storage C#.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.


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

Weitere Informationen finden Sie in der API-Referenzdokumentation zu Cloud Storage Go.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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

Weitere Informationen finden Sie in der API-Referenzdokumentation zu Cloud Storage Java.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich bei Cloud Storage zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

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.