Cargas de transmisión

Cloud Storage admite la transmisión de datos a un bucket sin necesidad de que los datos se guarden primero en un archivo. Esto es útil cuando quieres subir datos, pero no sabes cuál es el tamaño final al comienzo de la carga, como cuando se generan los datos de carga de un proceso o cuando se comprime un objeto sobre la marcha.

Usa la validación de la suma de verificación durante la transmisión

Debido a que solo se puede proporcionar una suma de verificación en la solicitud inicial de una carga, a menudo no es factible usar la validación de suma de verificación de Cloud Storage durante la transmisión. Se recomienda que siempre uses la validación de la suma de verificación y puedes hacerlo de forma manual después de que se complete una carga de transmisión. Sin embargo, realizar la validación después de que se complete la transferencia significa que se puede acceder a los datos dañados durante el tiempo que lleva confirmar el daño y quitarlo.

Si necesitas validación de la suma de comprobación antes de que se complete la carga y se puede acceder a los datos, no debes usar una carga de transmisión. Debes usar una opción de carga diferente que realice la validación de la suma de verificación antes de finalizar el objeto.

Roles obligatorios

Para obtener los permisos que necesitas a fin de transmitir cargas, pídele a tu administrador que te otorgue uno de los siguientes roles:

• Para las cargas que incluyen un bloqueo de retención de objetos, pídele a tu administrador que te otorgue el rol de IAM de Administrador de objetos de almacenamiento (roles/storage.objectAdmin) para el bucket.

• Para todos los demás casos, pídele a tu administrador que te otorgue el rol de IAM de usuario de objeto de almacenamiento (roles/storage.objectUser) para el bucket.

Estos roles predefinidos contienen los permisos necesarios para transmitir cargas a Cloud Storage. Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

• storage.objects.create
• storage.objects.delete
• Este permiso solo es necesario para las cargas que reemplazan un objeto existente.
• storage.objects.list
• Este permiso solo es necesario para usar Google Cloud CLI a fin de realizar las instrucciones de esta página.
• storage.objects.setRetention
  • Este permiso solo es necesario para las cargas que incluyen un bloqueo de retención de objetos.

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

Para obtener más información sobre cómo otorgar roles en los buckets, consulta Usa IAM con buckets.

Realiza una carga de transmisión

En los siguientes ejemplos, se muestra cómo realizar una carga de transmisión desde un proceso a un objeto de Cloud Storage:

Console

La consola de Google Cloud no admite la carga de transmisiones. En su lugar, usa la CLI de gcloud.

Línea de comandos

1. Canaliza 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 desde el que recopilas datos. Por ejemplo, collect_measurements
   • BUCKET_NAME es el nombre del bucket 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 cliente

C++

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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#

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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}"

API de REST

API de JSON

Para realizar una carga de transmisión, usa uno de los siguientes métodos:

• Una carga reanudable, con los siguientes ajustes:

  • Cuando subas los datos del archivo, usa una carga en varios fragmentos.

  • Dado que no conoces el tamaño total del archivo hasta llegar al fragmento final, usa 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 512K, el encabezado Content-Range del fragmento es bytes 0-524287/*. Si tu carga tiene 64,000 bytes restantes después del primer fragmento, debes enviar un fragmento final que contenga los bytes restantes y tenga un encabezado Content-Range con el valor bytes 524288-588287/588288.

• Una carga de solicitud única, con los siguientes ajustes:

  • Incluye un encabezado Transfer-Encoding: chunked y excluye el encabezado Content-Length.

  • Crea la solicitud según las especificaciones y envía los datos del objeto en fragmentos a medida que estén disponibles.

API de XML

Para realizar una carga de transmisión, usa uno de los siguientes métodos:

• Una carga multiparte de la API de XML

• Una carga reanudable, con los siguientes ajustes:

  • Cuando subas los datos del archivo, usa una carga en varios fragmentos.

  • Dado que no conoces el tamaño total del archivo hasta llegar al fragmento final, usa 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 512K, el encabezado Content-Range del fragmento es bytes 0-524287/*. Si tu carga tiene 64,000 bytes restantes después del primer fragmento, debes enviar un fragmento final que contenga los bytes restantes y tenga un encabezado Content-Range con el valor bytes 524288-588287/588288.

• Una carga de solicitud única, con los siguientes ajustes:

  • Incluye un encabezado Transfer-Encoding: chunked y excluye el encabezado Content-Length.

  • Crea la solicitud de acuerdo con la especificación y envía los datos del objeto en fragmentos a medida que estén disponibles.

  • Ten en cuenta que no puedes realizar una carga de transmisión con este método si la solicitud usa una firma en su encabezado Authorization.

¿Qué sigue?

• Transmite una descarga
• Obtén más información sobre la transcodificación descompresiva.
• Obtén más información sobre cargas y descargas.