Caricamenti di flussi di dati

Cloud Storage supporta lo streaming dei dati in un bucket senza richiedere che i dati vengano prima salvati in un file. Questa funzionalità è utile quando vuoi caricare dati, ma non conosci le dimensioni finali all'inizio del caricamento, ad esempio quando generi i dati di caricamento da un processo o quando comprimi un oggetto al volo.

Utilizzare la convalida del checksum durante lo streaming

Poiché un checksum può essere fornito solo nella richiesta iniziale di un caricamento, spesso non è fattibile utilizzare la convalida del checksum di Cloud Storage durante lo streaming. Ti consigliamo di utilizzare sempre la convalida del checksum, che puoi eseguire manualmente al termine di un caricamento in streaming. Tuttavia, la convalida al termine del trasferimento significa che tutti i dati danneggiati sono accessibili durante il tempo necessario per confermare il danneggiamento e rimuoverli.

Se hai bisogno della convalida del checksum prima del completamento del caricamento e che i dati diventino accessibili, non devi utilizzare un caricamento in streaming. Devi utilizzare un'opzione di caricamento diversa che esegua la convalida del checksum prima di finalizzare l'oggetto.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per lo streaming dei caricamenti, chiedi all'amministratore di concederti uno dei seguenti ruoli:

• Per i caricamenti che includono un blocco della conservazione degli oggetti, chiedi all' amministratore di concederti il ruolo IAM Amministratore oggetti Storage (roles/storage.objectAdmin) per il bucket.

• In tutti gli altri casi, chiedi all'amministratore di concederti il ruolo IAM Utente oggetti Storage (roles/storage.objectUser) per il bucket.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per lo streaming dei caricamenti in Cloud Storage. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

• storage.objects.create
• storage.objects.delete
• Questa autorizzazione è necessaria solo per i caricamenti che sovrascrivono un oggetto esistente.
• storage.objects.list
• Questa autorizzazione è necessaria solo per utilizzare Google Cloud CLI per eseguire le istruzioni riportate in questa pagina.
• storage.objects.setRetention
  • Questa autorizzazione è necessaria solo per i caricamenti che includono un blocco della conservazione degli oggetti.

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

Per informazioni sulla concessione dei ruoli nei bucket, consulta Impostare e gestire i criteri IAM nei bucket.

Eseguire lo streaming di un caricamento

Gli esempi riportati di seguito mostrano come eseguire un caricamento in streaming da un processo a un oggetto Cloud Storage:

Console

La Google Cloud console non supporta i caricamenti in streaming. Utilizza invece gcloud CLI.

Riga di comando

1. Invia i dati tramite pipe al comando gcloud storage cp e utilizza un trattino per l'URL di origine:

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

   Dove:

   • PROCESS_NAME è il nome del processo da cui stai raccogliendo i dati. Ad esempio, collect_measurements.
   • BUCKET_NAME è il nome del bucket contenente l'oggetto. Ad esempio, my_app_bucket.
   • OBJECT_NAME è il nome dell'oggetto creato dai dati. Ad esempio, data_measurements.

Librerie client

C++

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

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& 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#

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

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

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

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 (
	"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

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

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

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

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

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

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;
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

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

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

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.

# 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}"

Rust

use bytes::Bytes;
use google_cloud_storage::{client::Storage, streaming_source::StreamingSource};

pub async fn sample(client: &Storage, bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "object-to-upload.txt";
    let payload = Payload(100);
    let object = client
        .write_object(format!("projects/_/buckets/{bucket_id}"), NAME, payload)
        .set_if_generation_match(0)
        .send_buffered()
        .await?;
    println!("successfully uploaded object {NAME} to bucket {bucket_id}: {object:?}");
    Ok(())
}

struct Payload(i32);

impl StreamingSource for Payload {
    type Error = std::convert::Infallible;
    async fn next(&mut self) -> Option<Result<bytes::Bytes, Self::Error>> {
        if self.0 <= 0 {
            return None;
        }
        let value = format!("still have to send {} lines\n", self.0);
        self.0 -= 1;
        Some(Ok(Bytes::from_owner(value)))
    }
}

API REST

API JSON

Per eseguire un caricamento in streaming, utilizza uno dei seguenti metodi:

• Un caricamento ripristinabile, con le seguenti modifiche:

  • Quando carichi i dati del file, utilizza un caricamento di più blocchi.

  • Poiché non conosci le dimensioni totali del file fino all'ultimo blocco, utilizza un * per le dimensioni totali del file nell'intestazione Content-Range dei blocchi intermedi.

    Ad esempio, se il primo blocco che carichi ha una dimensione di 512 KiB, l'intestazione Content-Range del blocco è bytes 0-524287/*. Se dopo il primo blocco rimangono 64.000 byte da caricare, invia un blocco finale che contiene i byte rimanenti e ha un'intestazione Content-Range con il valore bytes 524288-588287/588288.

• Un caricamento con una singola richiesta, con le seguenti modifiche:

  • Includi un'Transfer-Encoding: chunked header ed escludi l'Content-Length header.

  • Costruisci la richiesta in base alla specifica, inviando i dati dell'oggetto in blocchi man mano che diventano disponibili.

API XML

Per eseguire un caricamento in streaming, utilizza uno dei seguenti metodi:

• Un caricamento in più parti dell'API XML

• Un caricamento ripristinabile, con le seguenti modifiche:

  • Quando carichi i dati del file, utilizza un caricamento di più blocchi.

  • Poiché non conosci le dimensioni totali del file fino all'ultimo blocco, utilizza un * per le dimensioni totali del file nell'intestazione Content-Range dei blocchi intermedi.

    Ad esempio, se il primo blocco che carichi ha una dimensione di 512 KiB, l'intestazione Content-Range del blocco è bytes 0-524287/*. Se dopo il primo blocco rimangono 64.000 byte da caricare, invia un blocco finale che contiene i byte rimanenti e ha un'intestazione Content-Range con il valore bytes 524288-588287/588288.

• Un caricamento con una singola richiesta, con le seguenti modifiche:

  • Includi un'Transfer-Encoding: chunked header ed escludi l'Content-Length header.

  • Costruisci la richiesta in base alla specifica, inviando i dati dell'oggetto in blocchi man mano che diventano disponibili.

  • Tieni presente che non puoi eseguire un caricamento in streaming utilizzando questo metodo se la richiesta utilizza una firma nella sua Authorization intestazione.

Passaggi successivi

• Eseguire lo streaming di un download.
• Scopri di più sulla transcodifica decompressiva.
• Scopri di più sui caricamenti di oggetti.