Objekte zusammensetzen

Overview

Auf dieser Seite erfahren Sie, wie Sie Cloud Storage-Objekte in einem einzelnen Objekt zusammenfassen. Eine Anfrage zur Zusammensetzung umfasst 1 bis 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.

Beachten Sie beim Zusammensetzen von Objekten Folgendes:

Die Quellobjekte sind vom Zusammensetzungsprozess nicht betroffen. Wenn es sich dabei um temporäre Objekte handeln soll, müssen Sie diese löschen, sobald Sie die Zusammensetzung erfolgreich abgeschlossen haben.

Da für andere Speicherklassen Gebühren für vorzeitiges Löschen anfallen, sollten Sie für temporäre Objekte immer Standard Storage verwenden.

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 Erstellen von Objekten benötigen. Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen 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 separat in Ihrem 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 außerdem die Berechtigung storage.objects.setRetention. Bitten Sie Ihren Administrator, Ihnen die Rolle „Storage-Objekt-Administrator“ (roles/storage.objectAdmin) anstelle von „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 mit Buckets verwenden.

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

Wobei:

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.

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 eine lokale Entwicklungsumgebung 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) {
  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#

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


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

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

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

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.

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

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

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

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.

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 APIs

JSON API

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

Alternativ können Sie mit dem OAuth 2.0 Playground ein Zugriffstoken erstellen und in den Header Authorization einfügen.
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"
  }
}
```
Wobei:
- 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.
Verwenden Sie cURL, um die JSON API mit einer POST-Objektanfrage 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"
```
Wobei:
- 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

Die gcloud CLI installieren und initialisieren, um ein Zugriffstoken für den Header Authorization zu generieren.

Alternativ können Sie mit dem OAuth 2.0 Playground ein Zugriffstoken erstellen und in den Header Authorization einfügen.
Erstellen Sie eine XML-Datei, die Folgendes enthält:
```
  <ComposeRequest>
    <Component>
      <Name>SOURCE_OBJECT_1</Name>
    </Component>
    <Component>
      <Name>SOURCE_OBJECT_2</Name>
    </Component>
  </ComposeRequest>
```
Wobei:
- SOURCE_OBJECT_1 und SOURCE_OBJECT_2 sind die Namen der Quellobjekte, die in der Objektzusammensetzung verwendet werden sollen.
Verwenden Sie cURL, um die XML API mit einer PUT-Objektanfrage und dem Abfragestringparameter compose aufzurufen:
```
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"
```
Wobei:
- 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.