Leituras de streaming

O Cloud Storage oferece suporte a leituras de objetos por streaming, o que permite que um aplicativo ou processo consuma fluxos de bytes de objetos em tempo real diretamente pela conexão de rede sem salvar uma cópia dos dados em um disco local ou armazenamento permanente.

Se você quiser fazer o download de um objeto e salvá-lo no sistema de arquivos local, consulte Fazer o download de objetos como arquivos.

Como usar a validação da soma de verificação durante o streaming de leituras

Não use uma leitura por streaming se a validação da soma de verificação antes for necessária do processamento de dados. Como as leituras de streaming geralmente usam o cabeçalho HTTP Range, o Cloud Storage não retorna somas de verificação que se aplicam apenas a uma parte arbitrária solicitada dos dados do objeto. As somas de verificação do servidor validam o objeto completo, o que significa que dados corrompidos podem ser lidos e processados antes que o fluxo completo seja concluído e validado.

Funções exigidas

Para receber as permissões necessárias para fazer leituras de streaming, peça ao administrador para conceder a você o papel de Leitor de objetos do Storage (roles/storage.objectViewer) no bucket.

Esse papel tem a permissão necessária para fazer streaming de leituras. Para conferir a permissão exata necessária, expanda a seção Permissões necessárias:

Permissões necessárias

• storage.objects.get

Talvez você também possa receber essa permissão com outros papéis predefinidos ou personalizados.

Para instruções sobre como conceder papéis nos buckets, consulte Definir e gerenciar políticas do IAM em buckets.

Transmitir uma leitura de objeto

Os exemplos a seguir mostram como realizar uma leitura transmitida de um objeto do Cloud Storage para um processo:

Observação: dependendo da linguagem de programação, algumas das amostras de código a seguir são escritas para demonstrar pipelines de streaming transmitindo dados do Cloud Storage e gravando os dados em um destino de arquivo local no disco. Embora salvar diretamente no disco constitua um download físico, esses exemplos são fornecidos aqui porque demonstram a sintaxe subjacente para processar canais de dados incrementais abertos. Para converter essas amostras em leituras de streaming na memória, troque os destinos de fluxo de arquivos locais de acordo com as necessidades do seu aplicativo.

Console

O console Google Cloud não é compatível com leituras por streaming. Use a Google Cloud CLI.

Linha de comando

1. Execute o comando gcloud storage cp usando um traço para o URL de destino. Em seguida, direcione os dados para o processo:

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

   Em que:

   • BUCKET_NAME é o nome do bucket que contém o objeto. Por exemplo, my_app_bucket.
   • OBJECT_NAME é o nome do objeto que você está transmitindo para o processo. Por exemplo, data_measurements.
   • PROCESS_NAME é o nome do processo no qual você está inserindo dados. Por exemplo, analyze_data.

Também é possível realizar a transferência por streaming dos dados de um objeto do Cloud Storage para um comando padrão do Linux, como sort:

gcloud storage cp gs://my_app_bucket/data_measurements - | sort

Observação: para objetos que contêm apenas uma soma de verificação CRC32C (como objetos compostos ou objetos na classe de armazenamento Rapid), a Google Cloud CLI depende estritamente das validações de soma de verificação. Por padrão, a Google Cloud CLI usa a biblioteca Python google-crc32c, que tem alta performance. O binário google-crc32c vem pré-instalado com a Google Cloud CLI, que tem uma instalação do Python agrupada. Se você estiver usando uma instalação do Python não agrupada, poderá ter um desempenho mais lento se o método de validação de substituição (o binário gcloud-crc32c) for usado. Para otimizar leituras de streaming, instale explicitamente a biblioteca google-crc32c do PyPI.

Bibliotecas de cliente

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage C++.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  gcs::ObjectReadStream stream = client.ReadObject(bucket_name, object_name);

  int count = 0;
  std::string line;
  while (std::getline(stream, line, '\n')) {
    ++count;
  }
  if (stream.bad()) throw google::cloud::Status(stream.status());

  std::cout << "The object has " << count << " lines\n";
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage C#.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

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

public class DownloadFileSample
{
    public void DownloadFile(
        string bucketName = "your-unique-bucket-name",
        string objectName = "my-file-name",
        string localPath = "my-local-path/my-file-name")
    {
        var storage = StorageClient.Create();
        using var outputFile = File.OpenWrite(localPath);
        storage.DownloadObject(bucketName, objectName, outputFile);
        Console.WriteLine($"Downloaded {objectName} to {localPath}.");
    }
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage Go.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

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

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

// downloadFileIntoMemory downloads an object.
func downloadFileIntoMemory(w io.Writer, bucket, object string) ([]byte, error) {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

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

	rc, err := client.Bucket(bucket).Object(object).NewReader(ctx)
	if err != nil {
		return nil, fmt.Errorf("Object(%q).NewReader: %w", object, err)
	}
	defer rc.Close()

	data, err := io.ReadAll(rc)
	if err != nil {
		return nil, fmt.Errorf("io.ReadAll: %w", err)
	}
	fmt.Fprintf(w, "Blob %v downloaded.\n", object)
	return data, nil
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

import com.google.cloud.ReadChannel;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.io.ByteStreams;
import java.io.IOException;
import java.nio.channels.FileChannel;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.StandardOpenOption;

public class StreamObjectDownload {

  public static void streamObjectDownload(
      String projectId, String bucketName, String objectName, String targetFile)
      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 path to the file to download the object to
    // String targetFile = "path/to/your/file";
    Path targetFilePath = Paths.get(targetFile);

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    try (ReadChannel reader = storage.reader(BlobId.of(bucketName, objectName));
        FileChannel targetFileChannel =
            FileChannel.open(targetFilePath, StandardOpenOption.WRITE)) {

      ByteStreams.copy(reader, targetFileChannel);

      System.out.println(
          "Downloaded object "
              + objectName
              + " from bucket "
              + bucketName
              + " to "
              + targetFile
              + " using a ReadChannel.");
    }
  }
}

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage Node.js.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação 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 ID of your GCS file
// const fileName = 'your-file-name';

// The filename and file path where you want to download the file
// const destFileName = '/local/path/to/file.txt';

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

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

async function streamFileDownload() {
  // The example below demonstrates how we can reference a remote file, then
  // pipe its contents to a local file.
  // Once the stream is created, the data can be piped anywhere (process, sdout, etc)
  await storage
    .bucket(bucketName)
    .file(fileName)
    .createReadStream() //stream is created
    .pipe(fs.createWriteStream(destFileName))
    .on('finish', () => {
      // The file download is complete
    });

  console.log(
    `gs://${bucketName}/${fileName} downloaded to ${destFileName}.`
  );
}

streamFileDownload().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage PHP.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\Storage\StorageClient;

/**
 * Download an object from Cloud Storage and save it as a local file.
 *
 * @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 $destination The local destination to save the object.
 *        (e.g. '/path/to/your/file')
 */
function download_object(string $bucketName, string $objectName, string $destination): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->downloadToFile($destination);
    printf(
        'Downloaded gs://%s/%s to %s' . PHP_EOL,
        $bucketName,
        $objectName,
        basename($destination)
    );
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage Python.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

from google.cloud import storage


def download_blob_to_stream(bucket_name, source_blob_name, file_obj):
    """Downloads a blob to a stream or other file-like object."""

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

    # The ID of your GCS object (blob)
    # source_blob_name = "storage-object-name"

    # The stream or file (file-like object) to which the blob will be written
    # import io
    # file_obj = io.BytesIO()

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Construct a client-side representation of a blob.
    # Note `Bucket.blob` differs from `Bucket.get_blob` in that it doesn't
    # retrieve metadata from Google Cloud Storage. As we don't use metadata in
    # this example, using `Bucket.blob` is preferred here.
    blob = bucket.blob(source_blob_name)
    blob.download_to_file(file_obj)

    print(f"Downloaded blob {source_blob_name} to file-like object.")

    return file_obj
    # Before reading from file_obj, remember to rewind with file_obj.seek(0).

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage Ruby.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

# Downloads a blob to a stream or other file-like object.

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

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

# The stream or file (file-like object) to which the contents will be written
# local_file_obj = StringIO.new

require "google/cloud/storage"

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

file.download local_file_obj, verify: :none

# rewind the object before starting to read the downloaded contents
local_file_obj.rewind
puts "The full downloaded file contents are: #{local_file_obj.read.inspect}"

Rust

use google_cloud_storage::client::Storage;

pub async fn sample(client: &Storage, bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "object-to-download.txt";
    let mut reader = client
        .read_object(format!("projects/_/buckets/{bucket_id}"), NAME)
        .send()
        .await?;
    println!("counting newlines {NAME} in bucket {bucket_id}");
    let mut count = 0;
    while let Some(buffer) = reader.next().await.transpose()? {
        count += buffer.into_iter().filter(|c| *c == b'\n').count();
    }
    println!("object {NAME} in bucket {bucket_id} contains {count} newlines");
    Ok(())
}

APIs REST

API JSON

Para executar uma leitura por streaming, siga as instruções para fazer o download de um objeto com as seguintes considerações:

• Antes de começar a leitura, recupere os metadados do objeto e salve o número de geração. Inclua esse número de geração em todas as suas solicitações para garantir que você não leia dados de duas gerações diferentes no caso de a original ser substituída.

• Use o cabeçalho Range na solicitação para recuperar uma parte do objeto geral, que pode ser enviada ao processo local.

• Continue fazendo solicitações para partes sucessivas do objeto até que todo o objeto seja recuperado.

API XML

Para executar uma leitura por streaming, siga as instruções para fazer o download de um objeto com as seguintes considerações:

• Antes de começar a leitura, recupere os metadados do objeto e salve o número de geração. Inclua esse número de geração em todas as suas solicitações para garantir que você não leia dados de duas gerações diferentes no caso de a original ser substituída.

• Use o cabeçalho Range na solicitação para recuperar uma parte do objeto geral, que pode ser enviada ao processo local.

• Continue fazendo solicitações para partes sucessivas do objeto até que todo o objeto seja recuperado.

A seguir

• Fazer streaming de um upload
• Saiba mais sobre transcodificação de descompactação.
• Saiba mais sobre leituras e downloads de objetos.