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.

Ler objetos

Nesta página, mostramos como ler dados de objetos dos buckets do Cloud Storage diretamente na memória do aplicativo ou de forma interativa no navegador da Web ou no terminal de linha de comando. A leitura de objetos na memória ou de forma interativa é recomendada quando você quer transmitir, inspecionar ou processar dados de uma maneira que evite a sobrecarga de CPU, E/S de disco e latência associada à gravação de arquivos em um sistema de arquivos local persistente.

Para instruções sobre como fazer o download de objetos no armazenamento persistente ou local, consulte Fazer o download de objetos. Para uma visão geral conceitual das leituras e downloads de objetos, consulte Leituras e downloads de objetos.

Funções exigidas

Para conseguir as permissões que você precisa para ler dados de objetos, peça ao administrador para conceder a você os seguintes papéis do IAM:

Leitor de objetos do Storage (roles/storage.objectViewer) no bucket
Administrador do Storage (roles/storage.admin) no projeto (necessário apenas para ler dados de objetos usando o Google Cloud console)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

O papel Leitor de objetos do Storage (roles/storage.objectViewer) contém a permissão storage.objects.get, que é necessária para ler objetos. O papel Administrador do Storage (roles/storage.admin) contém as permissões storage.buckets.list e storage.buckets.get, além da permissão storage.objects.get. Essas permissões são necessárias para listar os buckets em um projeto e visualizar informações sobre eles. O papel Administrador do Storage (roles/storage.admin) que inclui essas permissões só é necessário quando você quer ler objetos de forma interativa usando o Google Cloud console.

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

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

Ler objetos programaticamente na memória

Esta seção descreve como ler dados de objetos transmitindo os bytes do objeto diretamente para a memória do aplicativo.

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);
  std::string buffer{std::istreambuf_iterator<char>(stream),
                     std::istreambuf_iterator<char>()};
  if (stream.bad()) throw google::cloud::Status(stream.status());

  std::cout << "The object has " << buffer.size() << " characters\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 DownloadObjectIntoMemorySample
{
    public Stream DownloadObjectIntoMemory(
        string bucketName = "unique-bucket-name",
        string objectName = "file-name")
    {
        var storage = StorageClient.Create();
        Stream stream = new MemoryStream();
        storage.DownloadObject(bucketName, objectName, stream);

        Console.WriteLine($"The contents of {objectName} from bucket {bucketName} are downloaded");
        return stream;
    }
}

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.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.nio.charset.StandardCharsets;

public class DownloadObjectIntoMemory {
  public static void downloadObjectIntoMemory(
      String projectId, String bucketName, String objectName) {
    // 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";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    byte[] content = storage.readAllBytes(bucketName, objectName);
    System.out.println(
        "The contents of "
            + objectName
            + " from bucket name "
            + bucketName
            + " are: "
            + new String(content, StandardCharsets.UTF_8));
  }
}

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

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

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

async function downloadIntoMemory() {
  // Downloads the file into a buffer in memory.
  const contents = await storage.bucket(bucketName).file(fileName).download();

  console.log(
    `Contents of gs://${bucketName}/${fileName} are ${contents.toString()}.`
  );
}

downloadIntoMemory().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 into a buffer in memory.
 *
 * @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')
 */
function download_object_into_memory(
    string $bucketName,
    string $objectName
): void {
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $contents = $object->downloadAsString();
    printf(
        'Downloaded %s from gs://%s/%s' . PHP_EOL,
        $contents,
        $bucketName,
        $objectName
    );
}

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_into_memory(bucket_name, blob_name):
    """Downloads a blob into memory."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The ID of your GCS object
    # blob_name = "storage-object-name"

    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` as it doesn't retrieve
    # any content from Google Cloud Storage. As we don't need additional data,
    # using `Bucket.blob` is preferred here.
    blob = bucket.blob(blob_name)
    contents = blob.download_as_bytes()

    print(
        "Downloaded storage object {} from bucket {} as the following bytes object: {}.".format(
            blob_name, bucket_name, contents.decode("utf-8")
        )
    )

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.

# The name of the bucket to access
# bucket_name = "my-bucket"

# The name of the remote file to download
# file_name = "file.txt"

require "google/cloud/storage"

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

downloaded = file.download
downloaded.rewind # Optional - not needed on first read
contents = downloaded.read

puts "Contents of storage object #{file.name} in bucket #{bucket_name} are: #{contents}"

Rust

use google_cloud_storage::client::Storage;

pub async fn sample(client: &Storage, bucket: &str) -> Result<(), anyhow::Error> {
    const NAME: &str = "object-to-download.txt";
    let mut reader = client
        .read_object(format!("projects/_/buckets/{bucket}"), NAME)
        .send()
        .await?;

    let mut content = Vec::new();
    while let Some(data) = reader.next().await.transpose()? {
        content.extend_from_slice(&data);
    }

    println!(
        "Downloaded {} bytes of object {NAME} in bucket {bucket}.",
        content.len()
    );
    Ok(())
}

Ler objetos de forma interativa

Esta seção descreve como ler objetos de forma interativa na Google Cloud janela do navegador do console ou no terminal de linha de comando stdout.

Console

No Google Cloud console do, acesse a página Buckets do Cloud Storage.

Acessar buckets
Na lista de buckets, clique no nome do bucket cujo conteúdo você quer visualizar.
Na guia Objetos, clique no nome do objeto que você quer ler.
Na página Detalhes do objeto, clique no URL público ou autenticado do objeto para ler os dados dele.

Linha de comando

Para transmitir o payload de bytes de um objeto diretamente para o stdout do terminal, use o gcloud storage cat comando:

gcloud storage cat gs://BUCKET_NAME/OBJECT_NAME

Substitua:

BUCKET_NAME: o nome do bucket que contém o objeto que você quer ler. Por exemplo, my-bucket.
OBJECT_NAME: o nome do objeto que você quer ler. Por exemplo, dog.png.

APIs REST

Para ler os bytes de um objeto e direcionar o fluxo de saída para o stdout do terminal, use as instruções a seguir.

API JSON

Tenha a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.
Use cURL para chamar a API JSON com uma solicitação objects.get que inclua a opção -o - e o parâmetro de consulta alt=media:
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-o - \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"
```
Substitua:
- BUCKET_NAME: o nome do bucket que contém o objeto que você quer ler. Por exemplo, my-bucket.
- OBJECT_NAME: o nome codificado por URL do objeto que você quer ler. Por exemplo, pets/dog.png, codificado por URL como pets%2Fdog.png.

API XML

Tenha a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.
Use cURL para chamar a API XML com uma solicitação de objeto GET:
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
```
Substitua:
- BUCKET_NAME: o nome do bucket que contém o objeto que você quer ler. Por exemplo, my-bucket.
- OBJECT_NAME: o nome codificado por URL do objeto que você quer ler. Por exemplo, pets/dog.png, codificado por URL como pets%2Fdog.png.

A seguir

Transfira dados de provedores da nuvem ou de outras origens on-line, como listas de URLs.

Transfira objetos para sua instância do Compute Engine.

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

Funções exigidas

Ler objetos programaticamente na memória

Bibliotecas de cliente

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

Ler objetos de forma interativa

Console

Linha de comando

APIs REST

API JSON

API XML

A seguir

Ler objetos