Objekte zusammensetzen

Übersicht

Auf dieser Seite erfahren Sie, wie Sie mehrere Cloud Storage-Objekte in einem einzelnen Objekt zusammenfassen. Bei einer Zusammensetzungsanfrage werden zwischen 1 und 32 Objekte verwendet, um ein neues zusammengesetztes Objekt zu erstellen. Das zusammengesetzte Objekt ist eine Verkettung der Quellobjekte in der Reihenfolge, in der sie in der Anfrage angegeben wurden.

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

Kostenüberlegungen für temporäre Objekte

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

• Für Quellobjekte gelten je nach Speicherklasse Mindestspeicherdauern und es können Gebühren für vorzeitiges Löschen anfallen.

• Wenn vorläufiges Löschen oder die 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, was zusätzliche Speichergebühren verursachen kann.

• Um die Abrechnung für temporäre Objekte zu minimieren, löschen Sie die temporären Objekte während des Zusammensetzungsprozesses dauerhaft mit der Option deleteSourceObjects. Für Objekte, die mit dieser Option gelöscht werden, fallen keine Gebühren für vorzeitiges Löschen an. Außerdem werden Objekte, die mit dieser Option gelöscht werden, nicht durch vorläufiges Löschen oder die Objektversionsverwaltung aufbewahrt, da die Daten im zusammengesetzten Objekt aufbewahrt 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 im Google Cloud CLI Befehl auflisten zu müssen.

Wenn Sie eine Aufbewahrungskonfiguration für das Objekt festlegen möchten, das Sie zusammensetzen, benötigen Sie auch die storage.objects.setRetention Berechtigung. Bitten Sie Ihren 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 Zusammensetzungsprozesses löschen möchten, fügen Sie dem vorherigen Befehl das Flag --delete-source-objects hinzu.

Hinweis: Sie können auch einen Platzhalter verwenden, um Objekte mit einem gemeinsamen Präfix zusammenzusetzen, ohne im Befehl jedes Objekt einzeln auflisten zu müssen.

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

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 Referenzdokumentation zur Cloud Storage Go 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.

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, deleteSourceObjects bool) error {
	// bucket := "bucket-name"
	// object1 := "object-name-1"
	// object2 := "object-name-2"
	// toObject := "object-name-3"
	// deleteSourceObjects := true

	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 up to 32 source objects.
	composer := dst.ComposerFrom(src1, src2)
	composer.DeleteSourceObjects = deleteSourceObjects
	_, err = composer.Run(ctx)
	if err != nil {
		return fmt.Errorf("ComposerFrom: %w", err)
	}
	status := "Source objects were not deleted."
	if deleteSourceObjects {
		status = "The source objects were deleted."
	}
	fmt.Fprintf(w, "New composite object %v was created by combining %v and %v. %s\n", toObject, object1, object2, status)
	return nil
}

Java

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Java 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.

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Node.js 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.

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage PHP 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.

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')
 * @param bool $deleteSourceObjects Whether to delete the source objects after composition.
 *        (e.g. false)
 */
function compose_file(string $bucketName, string $firstObjectName, string $secondObjectName, string $targetObjectName, bool $deleteSourceObjects = false): 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
        );

        if ($deleteSourceObjects) {
            foreach ($objectsToCompose as $sourceObject) {
                $bucket->object($sourceObject)->delete();
            }
            printf(' and source objects were deleted');
        }
        printf(PHP_EOL);
    }
}

Python

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Python 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.

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

Weitere Informationen finden Sie in der Referenzdokumentation zur Cloud Storage Ruby 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.

def compose_file bucket_name:, first_file_name:, second_file_name:, destination_file_name:, delete_source_objects: false
  # 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, delete_source_objects: delete_source_objects 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}"
  puts "Source objects were deleted" if delete_source_objects
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 APIs

JSON-API

1. Installieren und initialisieren Sie die gcloud CLI, um ein Zugriffstoken für den Authorization Header zu generieren.

2. Erstellen Sie eine JSON-Datei, die folgende Informationen enthält:

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

   Dabei gilt:

   • SOURCE_OBJECT_1 und SOURCE_OBJECT_2 sind die Namen der Quellobjekte, die in der Objektzusammensetzung verwendet werden sollen.
   • COMPOSITE_OBJECT_CONTENT_TYPE ist der Inhaltstyp des resultierenden zusammengesetzten Objekts.
   • DELETE_SOURCE_OBJECTS_BOOLEAN wird auf true gesetzt, wenn Sie die Quellobjekte im Rahmen des Zusammensetzungsprozesses löschen möchten, oder auf false, wenn Sie die Quellobjekte beibehalten möchten. Der Standardwert ist false.

3. Verwenden Sie cURL, um die JSON API mit einer POST Objekt anfrage aufzurufen:

   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"

   Dabei gilt:

   • JSON_FILE_NAME ist der Name der Datei, die Sie im vorherigen Schritt erstellt haben.
   • BUCKET_NAME ist der Name des Buckets, der die Quellobjekte enthält.
   • COMPOSITE_OBJECT_NAME ist der Name, den Sie dem Ergebnis der Objektzusammensetzung geben.

Wenn der Vorgang erfolgreich abgeschlossen wurde, ist die Antwort eine Objektressource für das resultierende zusammengesetzte Objekt.

XML API

1. Installieren und initialisieren Sie die gcloud CLI, um ein Zugriffstoken für den Authorization Header zu generieren.

2. Erstellen Sie eine XML-Datei, die folgende Information enthält:

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

   Dabei gilt:

   • SOURCE_OBJECT_1 und SOURCE_OBJECT_2 sind die Namen der Quellobjekte, die in der Objektzusammensetzung verwendet werden sollen.

3. Verwenden Sie cURL, um die XML API mit einer PUT Objekt-Anfrage aufzurufen, die den compose Abfragestring parameter enthält:

   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"

   Dabei gilt:

   • XML_FILE_NAME ist der Name der Datei, die Sie im vorherigen Schritt erstellt haben.
   • COMPOSITE_OBJECT_CONTENT_TYPE ist der Inhaltstyp des resultierenden zusammengesetzten Objekts.
   • BUCKET_NAME ist der Name des Buckets, der die Quellobjekte enthält.
   • COMPOSITE_OBJECT_NAME ist der Name, den Sie dem Ergebnis der Objektzusammensetzung geben.

Wenn der Vorgang erfolgreich abgeschlossen wurde, wird ein leerer Antworttext zurückgegeben.

**Hinweis**: Die XML API unterstützt das Einschließen einer Generierungsnummer für jedes <Component>, was entweder mit einem <Generation>-Element oder einem <IfGenerationMatch>-Element möglich ist.

Nächste Schritte

• Mehr zu zusammengesetzten Objekten
• Anfragevorbedingungen verwenden, um Race-Bedingungen zu verhindern