Composer des objets

Présentation

Cette page vous explique comment composer des objets Cloud Storage en un seul objet. Une requête de composition prend entre 1 et 32 objets et crée un objet composite. L'objet composite est une concaténation des objets sources dans l'ordre dans lequel ils ont été spécifiés dans la requête.

Tenez compte des points suivants lorsque vous composez des objets :

• Les objets sources ne sont pas affectés par le processus de composition. Si ces objets sont censés être temporaires, vous devez les supprimer lorsque vous avez terminé la composition.

• Comme les autres classes de stockage sont soumises à des frais de suppression anticipée, vous devez toujours utiliser le stockage standard pour les objets temporaires.

Autorisations requises

Console

La console Google Cloud n'est pas compatible avec la composition d'objets. Utilisez plutôt la Google Cloud CLI.

Ligne de commande

Pour suivre ce guide à l'aide d'un utilitaire de ligne de commande, vous devez disposer des autorisations IAM appropriées. Si les buckets auxquels vous souhaitez accéder se trouvent dans un projet que vous n'avez pas créé, vous devrez peut-être demander au propriétaire du projet qu'il vous attribue un rôle contenant les autorisations nécessaires.

Pour obtenir la liste des autorisations requises pour des actions spécifiques, consultez la page Autorisations IAM pour les commandes gcloud storage.

Pour obtenir la liste des rôles pertinents, consultez la page Rôles Cloud Storage. Vous pouvez également créer un rôle personnalisé disposant d'autorisations limitées spécifiques.

Bibliothèques clientes

Pour suivre ce guide à l'aide des bibliothèques clientes Cloud Storage, vous devez disposer des autorisations IAM appropriées. Si les buckets auxquels vous souhaitez accéder se trouvent dans un projet que vous n'avez pas créé, vous devrez peut-être demander au propriétaire du projet qu'il vous attribue un rôle contenant les autorisations nécessaires.

Sauf indication contraire, les requêtes de bibliothèque cliente sont effectuées via l'API JSON et nécessitent des autorisations, comme indiqué dans la section Autorisations IAM pour les méthodes JSON. Pour savoir quelles méthodes d'API JSON sont appelées lorsque vous envoyez des requêtes à l'aide d'une bibliothèque cliente, consignez les requêtes brutes.

Pour obtenir la liste des rôles IAM pertinents, consultez la page Rôles Cloud Storage. Vous pouvez également créer un rôle personnalisé disposant d'autorisations limitées spécifiques.

API REST

API JSON

Pour suivre ce guide à l'aide de l'API JSON, vous devez disposer des autorisations IAM appropriées. Si les buckets auxquels vous souhaitez accéder se trouvent dans un projet que vous n'avez pas créé, vous devrez peut-être demander au propriétaire du projet qu'il vous attribue un rôle contenant les autorisations nécessaires.

Pour obtenir la liste des autorisations requises pour des actions spécifiques, consultez la page Autorisations IAM pour les méthodes JSON.

Pour obtenir la liste des rôles pertinents, consultez la page Rôles Cloud Storage. Vous pouvez également créer un rôle personnalisé disposant d'autorisations limitées spécifiques.

Créer un objet composite

Console

La console Google Cloud n'est pas compatible avec la composition d'objets. Utilisez plutôt la Google Cloud CLI.

Ligne de commande

Exécutez la commande 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

Où :

• BUCKET_NAME est le nom du bucket qui contient les objets sources ;
• SOURCE_OBJECT_1 et SOURCE_OBJECT_2 sont les noms des objets sources à utiliser dans la composition de l'objet ;
• COMPOSITE_OBJECT_NAME est le nom que vous donnez au résultat de la composition d'objet.

Remarque : Vous pouvez également utiliser un caractère générique pour composer des objets partageant un préfixe commun sans avoir à les répertorier séparément dans la commande.

Bibliothèques clientes

C++

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C++.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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#

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C#.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Go.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Ruby.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

API REST

API JSON

1. Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth. Pour obtenir des instructions, consultez la page Authentification des API.

2. Créez un fichier JSON contenant les informations suivantes :

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

   Où :

   • SOURCE_OBJECT_1 et SOURCE_OBJECT_2 sont les noms des objets sources à utiliser dans la composition de l'objet.
   • COMPOSITE_OBJECT_CONTENT_TYPE est le Content-Type de l'objet composite obtenu.

3. Exécutez la commande cURL pour appeler l'API JSON avec une requête POST Object :

   curl -X POST --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/COMPOSITE_OBJECT_NAME/compose"

   Où :

   • JSON_FILE_NAME est le nom du fichier que vous avez créé à l'étape précédente.
   • OAUTH2_TOKEN est le jeton d'accès généré plus tôt dans le guide.
   • BUCKET_NAME est le nom du bucket qui contient les objets sources.
   • COMPOSITE_OBJECT_NAME est le nom que vous donnez au résultat de la composition d'objet.

Si la requête aboutit, la réponse est une ressource d'objet pour l'objet composite obtenu.

API XML

1. Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth. Pour obtenir des instructions, consultez la page Authentification des API.

2. Créez un fichier XML contenant les informations suivantes :

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

   Où :

   • SOURCE_OBJECT_1 et SOURCE_OBJECT_2 sont les noms des objets sources à utiliser dans la composition de l'objet.

3. Utilisez cURL pour appeler l'API XML avec une requête d'objet PUT et un paramètre de chaîne de requête compose :

   curl -X PUT --data-binary @XML_FILE_NAME \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     -H "Content-Type: COMPOSITE_OBJECT_CONTENT_TYPE" \
     "https://storage.googleapis.com/BUCKET_NAME/COMPOSITE_OBJECT_NAME?compose"

   Où :

   • XML_FILE_NAME est le nom du fichier que vous avez créé à l'étape précédente.
   • OAUTH2_TOKEN est le jeton d'accès généré plus tôt dans le guide.
   • COMPOSITE_OBJECT_CONTENT_TYPE est le Content-Type de l'objet composite obtenu.
   • BUCKET_NAME est le nom du bucket qui contient les objets sources.
   • COMPOSITE_OBJECT_NAME est le nom que vous donnez au résultat de la composition d'objet.

Si la requête aboutit, un corps de réponse vide est renvoyé.

Remarque : L'API XML vous autorise à inclure un numéro de génération pour chaque composant (<Component>), en utilisant soit un élément <Generation> ou un élément <IfGenerationMatch>.

Étape suivante

• Apprenez-en plus sur la composition d'objets.
• Découvrez comment utiliser les conditions préalables de requête pour éviter les conditions de concurrence.