Subidas por streaming

Cloud Storage admite la transmisión de datos a un segmento sin necesidad de que los datos se guarden primero en un archivo. Esto resulta útil cuando quieres subir datos, pero no sabes el tamaño final al inicio de la subida, por ejemplo, cuando generas los datos de subida a partir de un proceso o cuando comprimes un objeto sobre la marcha.

Usar la validación de suma de comprobación al transmitir

Como solo se puede proporcionar una suma de comprobación en la solicitud inicial de una subida, a menudo no es viable usar la validación de la suma de comprobación de Cloud Storage al transmitir contenido. Te recomendamos que uses siempre la validación de suma de comprobación. Puedes hacerlo manualmente una vez que se haya completado la subida de la transmisión. Sin embargo, si validas los datos después de que se haya completado la transferencia, los datos dañados estarán accesibles durante el tiempo que se tarde en confirmar que están dañados y en eliminarlos.

Si necesitas validar la suma de comprobación antes de que se complete la subida y de que se pueda acceder a los datos, no debes usar una subida en streaming. Deberías usar otra opción de subida que realice la validación de la suma de comprobación antes de finalizar el objeto.

Roles obligatorios

Para obtener los permisos que necesitas para transmitir subidas, pide a tu administrador que te asigne uno de los siguientes roles:

  • En el caso de las subidas que incluyan un bloqueo de conservación de objetos, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Administrador de objetos de Storage (roles/storage.objectAdmin) para el segmento.

  • En el resto de los casos, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Usuario de objetos de Storage (roles/storage.objectUser) para el segmento.

Estos roles predefinidos contienen los permisos necesarios para transmitir subidas a Cloud Storage. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

  • storage.objects.create
  • storage.objects.delete
    • Este permiso solo es necesario para las subidas que sobrescriben un objeto.
  • storage.objects.list
    • Este permiso solo es necesario para usar la CLI de Google Cloud para seguir las instrucciones de esta página.
  • storage.objects.setRetention
    • Este permiso solo es necesario para las subidas que incluyan un bloqueo de conservación de objetos.

También puedes obtener estos permisos con otros roles predefinidos o roles personalizados.

Para obtener información sobre cómo conceder roles en los contenedores, consulta Usar IAM con contenedores.

Emitir una subida

En los ejemplos siguientes se muestra cómo realizar una subida en streaming desde un proceso a un objeto de Cloud Storage:

Consola

La consola no admite las subidas en streaming. Google Cloud Usa la CLI de gcloud.

Línea de comandos

  1. Transfiere los datos al comando gcloud storage cp y usa un guion para la URL de origen:

    PROCESS_NAME | gcloud storage cp - gs://BUCKET_NAME/OBJECT_NAME

    Donde:

    • PROCESS_NAME es el nombre del proceso del que recoges datos. Por ejemplo, collect_measurements.
    • BUCKET_NAME es el nombre del contenedor que contiene el objeto. Por ejemplo, my_app_bucket.
    • OBJECT_NAME es el nombre del objeto que se crea a partir de los datos. Por ejemplo, data_measurements.

Bibliotecas de cliente

C++

Para obtener más información, consulta la documentación de referencia de la API C++ de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, int desired_line_count) {
  std::string const text = "Lorem ipsum dolor sit amet";
  gcs::ObjectWriteStream stream =
      client.WriteObject(bucket_name, object_name);

  for (int lineno = 0; lineno != desired_line_count; ++lineno) {
    // Add 1 to the counter, because it is conventional to number lines
    // starting at 1.
    stream << (lineno + 1) << ": " << text << "\n";
  }

  stream.Close();

  StatusOr<gcs::ObjectMetadata> metadata = std::move(stream).metadata();
  if (!metadata) throw std::move(metadata).status();
  std::cout << "Successfully wrote to object " << metadata->name()
            << " its size is: " << metadata->size()
            << "\nFull metadata: " << *metadata << "\n";
}

C#

Para obtener más información, consulta la documentación de referencia de la API C# de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.


using Google.Cloud.Storage.V1;
using System;
using System.IO;

public class UploadFileSample
{
    public void UploadFile(
        string bucketName = "your-unique-bucket-name",
        string localPath = "my-local-path/my-file-name",
        string objectName = "my-file-name")
    {
        var storage = StorageClient.Create();
        using var fileStream = File.OpenRead(localPath);
        storage.UploadObject(bucketName, objectName, null, fileStream);
        Console.WriteLine($"Uploaded {objectName}.");
    }
}

Go

Para obtener más información, consulta la documentación de referencia de la API Go de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

import (
	"bytes"
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// streamFileUpload uploads an object via a stream.
func streamFileUpload(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	b := []byte("Hello world.")
	buf := bytes.NewBuffer(b)

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	// Upload an object with storage.Writer.
	wc := client.Bucket(bucket).Object(object).NewWriter(ctx)
	wc.ChunkSize = 0 // note retries are not supported for chunk size 0.

	if _, err = io.Copy(wc, buf); err != nil {
		return fmt.Errorf("io.Copy: %w", err)
	}
	// Data can continue to be added to the file until the writer is closed.
	if err := wc.Close(); err != nil {
		return fmt.Errorf("Writer.Close: %w", err)
	}
	fmt.Fprintf(w, "%v uploaded to %v.\n", object, bucket)

	return nil
}

Java

Para obtener más información, consulta la documentación de referencia de la API Java de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.


import com.google.cloud.WriteChannel;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.charset.StandardCharsets;

public class StreamObjectUpload {

  public static void streamObjectUpload(
      String projectId, String bucketName, String objectName, String contents) throws IOException {
    // 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 your GCS object
    // String objectName = "your-object-name";

    // The string of contents you wish to upload
    // String contents = "Hello world!";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, objectName);
    BlobInfo blobInfo = BlobInfo.newBuilder(blobId).build();
    byte[] content = contents.getBytes(StandardCharsets.UTF_8);
    try (WriteChannel writer = storage.writer(blobInfo)) {
      writer.write(ByteBuffer.wrap(content));
      System.out.println(
          "Wrote to " + objectName + " in bucket " + bucketName + " using a WriteChannel.");
    }
  }
}

Node.js

Para obtener más información, consulta la documentación de referencia de la API Node.js de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

/**
 * TODO(developer): Uncomment the following lines before running the sample
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The new ID for your GCS file
// const destFileName = 'your-new-file-name';

// The content to be uploaded in the GCS file
// const contents = 'your file content';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Import Node.js stream
const stream = require('stream');

// Creates a client
const storage = new Storage();

// Get a reference to the bucket
const myBucket = storage.bucket(bucketName);

// Create a reference to a file object
const file = myBucket.file(destFileName);

// Create a pass through stream from a string
const passthroughStream = new stream.PassThrough();
passthroughStream.write(contents);
passthroughStream.end();

async function streamFileUpload() {
  passthroughStream.pipe(file.createWriteStream()).on('finish', () => {
    // The file upload is complete
  });

  console.log(`${destFileName} uploaded to ${bucketName}`);
}

streamFileUpload().catch(console.error);

PHP

Para obtener más información, consulta la documentación de referencia de la API PHP de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

use Google\Cloud\Storage\StorageClient;
use Google\Cloud\Storage\WriteStream;

/**
 * Upload a chunked file stream.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param string $contents The contents to upload via stream chunks.
 *        (e.g. 'these are my contents')
 */
function upload_object_stream(string $bucketName, string $objectName, string $contents): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $writeStream = new WriteStream(null, [
        'chunkSize' => 1024 * 256, // 256KB
    ]);
    $uploader = $bucket->getStreamableUploader($writeStream, [
        'name' => $objectName,
    ]);
    $writeStream->setUploader($uploader);
    $stream = fopen('data://text/plain,' . $contents, 'r');
    while (($line = stream_get_line($stream, 1024 * 256)) !== false) {
        $writeStream->write($line);
    }
    $writeStream->close();

    printf('Uploaded %s to gs://%s/%s' . PHP_EOL, $contents, $bucketName, $objectName);
}

Python

Para obtener más información, consulta la documentación de referencia de la API Python de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

from google.cloud import storage


def upload_blob_from_stream(bucket_name, file_obj, destination_blob_name):
    """Uploads bytes from a stream or other file-like object to a blob."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The stream or file (file-like object) from which to read
    # import io
    # file_obj = io.BytesIO()
    # file_obj.write(b"This is test data.")

    # The desired name of the uploaded GCS object (blob)
    # destination_blob_name = "storage-object-name"

    # Construct a client-side representation of the blob.
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(destination_blob_name)

    # Rewind the stream to the beginning. This step can be omitted if the input
    # stream will always be at a correct position.
    file_obj.seek(0)

    # Upload data from the stream to your bucket.
    blob.upload_from_file(file_obj)

    print(
        f"Stream data uploaded to {destination_blob_name} in bucket {bucket_name}."
    )

Ruby

Para obtener más información, consulta la documentación de referencia de la API Ruby de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.


# The ID of your GCS bucket
# bucket_name = "your-unique-bucket-name"

# The stream or file (file-like object) from which to read
# local_file_obj = StringIO.new "This is test data."

# Name of a file in the Storage bucket
# file_name   = "some_file.txt"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

local_file_obj.rewind
bucket.create_file local_file_obj, file_name

puts "Stream data uploaded to #{file_name} in bucket #{bucket_name}"

APIs REST

API JSON

Para realizar una subida por streaming, utilice uno de los siguientes métodos:

  • Una subida reanudable con los siguientes ajustes:

    • Cuando suba los datos del archivo, utilice una subida de varios fragmentos.

    • Como no sabrá el tamaño total del archivo hasta que llegue al último fragmento, utilice un * para el tamaño total del archivo en el encabezado Content-Range de los fragmentos intermedios.

      Por ejemplo, si el primer fragmento que subes tiene un tamaño de 512 KiB, el encabezado Content-Range del fragmento es bytes 0-524287/*. Si a tu subida le quedan 64.000 bytes después del primer fragmento, envías un fragmento final que contiene los bytes restantes y tiene un encabezado Content-Range con el valor bytes 524288-588287/588288.

  • Una subida con una sola solicitud, con los siguientes ajustes:

API XML

Para realizar una subida por streaming, utilice uno de los siguientes métodos:

  • Una subida multiparte de la API XML

  • Una subida reanudable con los siguientes ajustes:

    • Cuando suba los datos del archivo, utilice una subida de varios fragmentos.

    • Como no sabrá el tamaño total del archivo hasta que llegue al último fragmento, utilice un * para el tamaño total del archivo en el encabezado Content-Range de los fragmentos intermedios.

      Por ejemplo, si el primer fragmento que subes tiene un tamaño de 512 KiB, el encabezado Content-Range del fragmento es bytes 0-524287/*. Si a tu subida le quedan 64.000 bytes después del primer fragmento, envías un fragmento final que contiene los bytes restantes y tiene un encabezado Content-Range con el valor bytes 524288-588287/588288.

  • Una subida con una sola solicitud, con los siguientes ajustes:

Siguientes pasos