O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Leituras de streaming

O Cloud Storage oferece suporte a leituras de objetos por streaming, o que permite que um aplicativo ou processo consuma streams 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 em vez disso.

Como usar a validação de checksum ao transmitir leituras

Não use uma leitura por streaming se você precisar de validação de checksum antes do tratamento de dados. Como as leituras por streaming normalmente usam o cabeçalho Range HTTP, o Cloud Storage não retorna somas de verificação que se aplicam apenas a uma parte solicitada arbitrária 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 stream completo seja concluído e validado.

Funções exigidas

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

Esse papel contém a permissão necessária para transmitir 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:

Console

O Google Cloud console não oferece suporte a leituras por streaming. Use a Google Cloud CLI.

Linha de comando

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

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 realizar uma leitura por streaming, siga as instruções para fazer o download de um objeto com as seguintes considerações:

Antes de iniciar a leitura, recupere os metadados do objeto e salve o número de geração dele. Inclua esse número de geração em cada uma das solicitações para garantir que você não leia dados de duas gerações diferentes caso o original seja substituído.
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 realizar uma leitura por streaming, siga as instruções para fazer o download de um objeto com as seguintes considerações:

Antes de iniciar a leitura, recupere os metadados do objeto e salve o número de geração dele. Inclua esse número de geração em cada uma das solicitações para garantir que você não leia dados de duas gerações diferentes caso o original seja substituído.
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.

Leituras de streaming Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Como usar a validação de checksum ao transmitir leituras

Funções exigidas

Permissões necessárias

Transmitir uma leitura de objeto

Console

Linha de comando

Bibliotecas de cliente

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

APIs REST

API JSON

API XML

A seguir

Leituras de streaming