Comporre oggetti

Panoramica

Questa pagina mostra come comporre più oggetti Cloud Storage in un unico oggetto. Una richiesta di composizione accetta da 1 a 32 oggetti e crea un nuovo oggetto composito. L'oggetto composito è una concatenazione degli oggetti di origine nell'ordine in cui sono stati specificati nella richiesta.

Gli oggetti di origine non vengono interessati, a meno che tu non decida di eliminarli durante il processo di composizione.

Considerazioni sui costi per gli oggetti temporanei

Se gli oggetti di origine devono essere temporanei, tieni presente le seguenti considerazioni sui costi durante la composizione degli oggetti:

• Gli oggetti di origine sono soggetti a durate minime di archiviazione, a seconda della classe di archiviazione, e potrebbero comportare tariffe per l'eliminazione anticipata.

• Se l'eliminazione temporanea o il controllo delle versioni degli oggetti sono abilitati, l'eliminazione degli oggetti di origine al termine della composizione può comportare l'eliminazione temporanea o la non attualità degli oggetti di origine, il che potrebbe comportare costi di archiviazione aggiuntivi.

• Per ridurre al minimo la fatturazione per gli oggetti temporanei, eliminali definitivamente durante il processo di composizione utilizzando l'opzione deleteSourceObjects. Gli oggetti eliminati con questa opzione non sono soggetti a tariffe per l'eliminazione anticipata. Inoltre, gli oggetti eliminati con questa opzione non vengono conservati dall'eliminazione temporanea o dal controllo delle versioni degli oggetti perché i dati vengono conservati nell'oggetto composito.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per comporre oggetti, chiedi all'amministratore di concederti il ruolo IAM Storage Object User (roles/storage.objectUser) sul bucket. Questo ruolo predefinito contiene le autorizzazioni necessarie per comporre gli oggetti. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

• storage.objects.create
• storage.objects.delete
  • Questa autorizzazione è richiesta solo se vuoi assegnare all'oggetto che componi lo stesso nome di un oggetto già esistente nel bucket.
• storage.objects.get
• storage.objects.list
  • Questa autorizzazione è necessaria solo se vuoi utilizzare i caratteri jolly per comporre oggetti con un prefisso comune senza dover elencare ogni oggetto separatamente nel comando Google Cloud CLI.

Se vuoi impostare una configurazione di conservazione per l'oggetto che componi, devi disporre anche dell'autorizzazione storage.objects.setRetention. Per ottenere questa autorizzazione, chiedi all'amministratore di concederti il ruolo Storage Object Admin (roles/storage.objectAdmin) anziché il ruolo Storage Object User (roles/storage.objectUser).

Puoi ottenere queste autorizzazioni anche con altri ruoli predefiniti o ruoli personalizzati.

Per informazioni sulla concessione di ruoli sui bucket, consulta Imposta e gestisci le policy IAM sui bucket.

Crea un oggetto composito

Riga di comando

Utilizza il comando 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

Dove:

• BUCKET_NAME è il nome del bucket che contiene gli oggetti di origine.
• SOURCE_OBJECT_1 e SOURCE_OBJECT_2 sono i nomi degli oggetti di origine da utilizzare nella composizione degli oggetti.
• COMPOSITE_OBJECT_NAME è il nome che stai assegnando al risultato della composizione degli oggetti.

Per eliminare gli oggetti di origine nell'ambito del processo di composizione, includi il flag --delete-source-objects nel comando precedente.

Nota: puoi anche utilizzare un carattere jolly per comporre oggetti con un prefisso comune senza dover elencare ogni oggetto separatamente nel comando.

Librerie client

C++

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage C++.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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#

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage C#.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Go.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Java.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Node.js.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage PHP.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Python.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Ruby.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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_if_generation_match() to make the 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(())
}

API REST

API JSON

1. Avere gcloud CLI installato e inizializzato, che ti consente di generare un token di accesso per l'intestazione Authorization.

2. Crea un file JSON che contenga le seguenti informazioni:

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

   Dove:

   • SOURCE_OBJECT_1 e SOURCE_OBJECT_2 sono i nomi degli oggetti di origine da utilizzare nella composizione degli oggetti.
   • COMPOSITE_OBJECT_CONTENT_TYPE è il Content-Type dell'oggetto composto risultante.
   • DELETE_SOURCE_OBJECTS_BOOLEAN è impostato su true se vuoi eliminare gli oggetti di origine nell'ambito del processo di composizione o su false se vuoi conservare gli oggetti di origine. Il valore predefinito è false.

3. Utilizza cURL per chiamare l'API JSON con una richiesta oggetto 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"

   Dove:

   • JSON_FILE_NAME è il nome del file che hai creato nel passaggio precedente.
   • BUCKET_NAME è il nome del bucket che contiene gli oggetti di origine.
   • COMPOSITE_OBJECT_NAME è il nome che stai assegnando al risultato della composizione degli oggetti.

In caso di esito positivo, la risposta è una risorsa oggetto per l'oggetto composto risultante.

API XML

1. Avere gcloud CLI installato e inizializzato, che ti consente di generare un token di accesso per l'intestazione Authorization.

2. Crea un file XML contenente le seguenti informazioni:

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

   Dove:

   • SOURCE_OBJECT_1 e SOURCE_OBJECT_2 sono i nomi degli oggetti di origine da utilizzare nella composizione degli oggetti.

3. Utilizza cURL per chiamare l'API XML con una richiesta PUT Object che include il parametro della stringa di query 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"

   Dove:

   • XML_FILE_NAME è il nome del file che hai creato nel passaggio precedente.
   • COMPOSITE_OBJECT_CONTENT_TYPE è il Content-Type dell'oggetto composto risultante.
   • BUCKET_NAME è il nome del bucket che contiene gli oggetti di origine.
   • COMPOSITE_OBJECT_NAME è il nome che stai assegnando al risultato della composizione degli oggetti.

In caso di esito positivo, viene restituito un corpo della risposta vuoto.

Nota: L'API XML supporta l'inclusione di un numero di generazione per ogni <Component>, utilizzando un elemento <Generation> o un elemento <IfGenerationMatch>.

Passaggi successivi

• Scopri di più sulla composizione degli oggetti.
• Scopri come utilizzare le precondizioni delle richieste per evitare le race condition.