Conferir o tamanho e os metadados do bucket

Conceitos

Nesta página, você aprenderá como receber informações sobre o tamanho e os metadados de buckets do Cloud Storage.

Permissões necessárias

Console

Para concluir este guia usando o Console do Google Cloud, é preciso ter as permissões de IAM adequadas. Se você não criou o bucket que quer acessar, talvez seja necessário que o proprietário do projeto atribua a você um papel que contenha as permissões necessárias.

Para uma lista de permissões necessárias para ações específicas, consulte Permissões do IAM para o Console do Google Cloud.

Para ver a lista de papéis relevantes, consulte Papéis do Cloud Storage. Como alternativa, é possível criar um papel personalizado que tenha permissões mais limitadas.

Linha de comando

Para concluir este guia usando um utilitário de linha de comando, você precisa ter as permissões de IAM adequadas. Se você não criou o bucket que quer acessar, talvez seja necessário que o proprietário do projeto atribua a você um papel que contenha as permissões necessárias.

Para uma lista de permissões necessárias para ações específicas, consulte Permissões do IAM para comandos gsutil.

Para ver a lista de papéis relevantes, consulte Papéis do Cloud Storage. Como alternativa, é possível criar um papel personalizado que tenha permissões mais limitadas.

Bibliotecas de cliente

Para concluir este guia usando as bibliotecas de cliente do Cloud Storage, é preciso ter as permissões de IAM adequadas. Se você não criou o bucket que quer acessar, talvez seja necessário que o proprietário do projeto conceda a você um papel que contenha as permissões necessárias.

A menos que indicado de outra forma, as solicitações da biblioteca de cliente são feitas por meio da API JSON e exigem permissões conforme listado nas permissões do IAM para métodos JSON. Para conferir quais métodos da API JSON são invocados ao fazer solicitações usando uma biblioteca de cliente, registre as solicitações brutas.

Para conferir a lista de papéis do IAM relevantes, consulte Papéis do Cloud Storage. Como alternativa, é possível criar um papel personalizado que tenha permissões mais limitadas.

APIs REST

API JSON

Para concluir este guia usando a API JSON, é preciso ter as permissões do IAM adequadas. Se você não criou o bucket que quer acessar, talvez seja necessário que o proprietário do projeto conceda a você um papel que contenha as permissões necessárias.

Para uma lista de permissões necessárias para ações específicas, consulte Permissões do IAM para métodos JSON.

Para ver a lista de papéis relevantes, consulte Papéis do Cloud Storage. Como alternativa, é possível criar um papel personalizado que tenha permissões mais limitadas.

Determinar o tamanho de um bucket

Console

Observação: o Monitoring mede o tamanho do bucket uma vez por dia e não informa buckets vazios. Para medir o tamanho do bucket em um determinado momento para qualquer bucket, use a gsutil.

Se quiser usar o Metrics Explorer para visualizar as métricas de um recurso monitorado, siga estes passos:

1. No Console do Google Cloud, acesse a página Metrics Explorer no Monitoring.

Acessar o Metrics Explorer

2. No painel Selecionar uma métrica, expanda o menu Métrica, insira Total bytes na barra de filtros e use os submenus para selecionar um tipo de recurso e métrica específicos:
   1. No menu Recursos ativos, selecione Bucket do GCS.
   2. No menu Categorias de métricas ativas, selecione Armazenamento.
   3. No menu Métricas ativas, selecione Total de bytes.
   4. Clique em Aplicar.
   O nome totalmente qualificado dessa métrica é storage.googleapis.com/storage/total_bytes.
3. Opcional: para configurar a visualização dos dados, adicione filtros, agrupamentos e configure os campos de alinhamento. Por padrão, o Metrics Explorer adiciona um agrupamento que faz a média de todas as séries temporais:
   • Para agrupar séries temporais por identificadores de recursos ou métricas, abra o menu Identificadores na seção Agrupar por e faça as seleções. Também é possível alterar a função de agrupamento.
   • Para visualizar todas as séries temporais, na entrada Agrupar por, clique em Excluir.
   • Para acessar os campos de alinhamento, clique em Mais opções.
   Para mais informações, consulte Selecionar métricas ao usar o Metrics Explorer.
4. Opcional: mude as configurações no painel Exibir:
   • Para cotas e outras métricas que registram uma amostra por dia, defina o Tipo de widget como Gráfico de barras empilhadas.
   • Para métricas de valor de distribuição, defina o tipo de widget como Gráfico de mapa de calor.
5. Opcional: para cota e outras métricas que registram uma amostra por dia, defina o período como pelo menos uma semana.

Use o Metrics Explorer também para medir outras métricas de bucket, como storage.googleapis.com/storage/object_count e storage.googleapis.com/storage/total_byte_seconds, que calculam, respectivamente, o número de objetos e a quantidade de armazenamento consumido diariamente. Consulte a documentação sobre métricas do Google Cloud para uma lista completa das métricas disponíveis. Consulte Métricas, séries temporais e recursos para mais informações sobre como usar o Metrics Explorer.

Linha de comando

Cuidado: o comando gsutil du faz muitas solicitações de listagem de objetos para calcular o uso de espaço utilizado, o que pode levar muito tempo no caso de buckets grandes. Se o número de objetos no bucket for de centenas de milhares ou mais, ou se você quiser monitorar o tamanho do bucket ao longo do tempo, use o Monitoring, conforme descrito na guia "Console".

Use o comando gsutil du com uma sinalização -s:

gsutil du -s gs://BUCKET_NAME

em que BUCKET_NAME é o nome do bucket pertinente.

A resposta terá esta aparência:

134620      gs://my-bucket

Nesse exemplo, o tamanho do bucket chamado my-bucket é 134.620 bytes.

Exibir os metadados de um intervalo

Console

1. No Console do Cloud, acesse a página Buckets do Cloud Storage.
   

   Acessar buckets

2. Na lista de buckets, clique no nome do bucket cujos metadados você quer ver.

3. Clique na guia Configuração para ver detalhes do bucket, como regiões incluídas, classe de armazenamento, permissões e tipo de replicação.

Linha de comando

Use o seguinte gsutil ls comando:

gsutil ls -L -b gs://BUCKET_NAME

em que BUCKET_NAME é o nome do bucket pertinente.

A resposta terá esta aparência:

gs://my-bucket/ :
  Storage class:              STANDARD
  Location type:              multi-region
  Location constraint:        US
  ...

Bibliotecas de cliente

C++

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Acessar no GitHub Feedback

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> bucket_metadata =
      client.GetBucketMetadata(bucket_name);
  if (!bucket_metadata) throw std::move(bucket_metadata).status();

  std::cout << "The metadata for bucket " << bucket_metadata->name() << " is "
            << *bucket_metadata << "\n";
}

C#

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Acessar no GitHub Feedback

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class GetBucketMetadataSample
{
    public Bucket GetBucketMetadata(string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.GetBucket(bucketName, new GetBucketOptions { Projection = Projection.Full });
        Console.WriteLine($"Bucket:\t{bucket.Name}");
        Console.WriteLine($"Acl:\t{bucket.Acl}");
        Console.WriteLine($"Billing:\t{bucket.Billing}");
        Console.WriteLine($"Cors:\t{bucket.Cors}");
        Console.WriteLine($"DefaultEventBasedHold:\t{bucket.DefaultEventBasedHold}");
        Console.WriteLine($"DefaultObjectAcl:\t{bucket.DefaultObjectAcl}");
        Console.WriteLine($"Encryption:\t{bucket.Encryption}");
        if (bucket.Encryption != null)
        {
            Console.WriteLine($"KmsKeyName:\t{bucket.Encryption.DefaultKmsKeyName}");
        }
        Console.WriteLine($"Id:\t{bucket.Id}");
        Console.WriteLine($"Kind:\t{bucket.Kind}");
        Console.WriteLine($"Lifecycle:\t{bucket.Lifecycle}");
        Console.WriteLine($"Location:\t{bucket.Location}");
        Console.WriteLine($"LocationType:\t{bucket.LocationType}");
        Console.WriteLine($"Logging:\t{bucket.Logging}");
        Console.WriteLine($"Metageneration:\t{bucket.Metageneration}");
        Console.WriteLine($"Owner:\t{bucket.Owner}");
        Console.WriteLine($"ProjectNumber:\t{bucket.ProjectNumber}");
        Console.WriteLine($"RetentionPolicy:\t{bucket.RetentionPolicy}");
        Console.WriteLine($"SelfLink:\t{bucket.SelfLink}");
        Console.WriteLine($"StorageClass:\t{bucket.StorageClass}");
        Console.WriteLine($"TimeCreated:\t{bucket.TimeCreated}");
        Console.WriteLine($"Updated:\t{bucket.Updated}");
        Console.WriteLine($"Versioning:\t{bucket.Versioning}");
        Console.WriteLine($"Website:\t{bucket.Website}");
        Console.WriteLine($"TurboReplication:\t{bucket.Rpo}");
        if (bucket.Labels != null)
        {
            Console.WriteLine("Labels:");
            foreach (var label in bucket.Labels)
            {
                Console.WriteLine($"{label.Key}:\t{label.Value}");
            }
        }
        return bucket;
    }
}

Go

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Acessar no GitHub Feedback

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

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

// getBucketMetadata gets the bucket metadata.
func getBucketMetadata(w io.Writer, bucketName string) (*storage.BucketAttrs, error) {
	// bucketName := "bucket-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*10)
	defer cancel()
	attrs, err := client.Bucket(bucketName).Attrs(ctx)
	if err != nil {
		return nil, fmt.Errorf("Bucket(%q).Attrs: %w", bucketName, err)
	}
	fmt.Fprintf(w, "BucketName: %v\n", attrs.Name)
	fmt.Fprintf(w, "Location: %v\n", attrs.Location)
	fmt.Fprintf(w, "LocationType: %v\n", attrs.LocationType)
	fmt.Fprintf(w, "StorageClass: %v\n", attrs.StorageClass)
	fmt.Fprintf(w, "Turbo replication (RPO): %v\n", attrs.RPO)
	fmt.Fprintf(w, "TimeCreated: %v\n", attrs.Created)
	fmt.Fprintf(w, "Metageneration: %v\n", attrs.MetaGeneration)
	fmt.Fprintf(w, "PredefinedACL: %v\n", attrs.PredefinedACL)
	if attrs.Encryption != nil {
		fmt.Fprintf(w, "DefaultKmsKeyName: %v\n", attrs.Encryption.DefaultKMSKeyName)
	}
	if attrs.Website != nil {
		fmt.Fprintf(w, "IndexPage: %v\n", attrs.Website.MainPageSuffix)
		fmt.Fprintf(w, "NotFoundPage: %v\n", attrs.Website.NotFoundPage)
	}
	fmt.Fprintf(w, "DefaultEventBasedHold: %v\n", attrs.DefaultEventBasedHold)
	if attrs.RetentionPolicy != nil {
		fmt.Fprintf(w, "RetentionEffectiveTime: %v\n", attrs.RetentionPolicy.EffectiveTime)
		fmt.Fprintf(w, "RetentionPeriod: %v\n", attrs.RetentionPolicy.RetentionPeriod)
		fmt.Fprintf(w, "RetentionPolicyIsLocked: %v\n", attrs.RetentionPolicy.IsLocked)
	}
	fmt.Fprintf(w, "RequesterPays: %v\n", attrs.RequesterPays)
	fmt.Fprintf(w, "VersioningEnabled: %v\n", attrs.VersioningEnabled)
	if attrs.Logging != nil {
		fmt.Fprintf(w, "LogBucket: %v\n", attrs.Logging.LogBucket)
		fmt.Fprintf(w, "LogObjectPrefix: %v\n", attrs.Logging.LogObjectPrefix)
	}
	if attrs.CORS != nil {
		fmt.Fprintln(w, "CORS:")
		for _, v := range attrs.CORS {
			fmt.Fprintf(w, "\tMaxAge: %v\n", v.MaxAge)
			fmt.Fprintf(w, "\tMethods: %v\n", v.Methods)
			fmt.Fprintf(w, "\tOrigins: %v\n", v.Origins)
			fmt.Fprintf(w, "\tResponseHeaders: %v\n", v.ResponseHeaders)
		}
	}
	if attrs.Labels != nil {
		fmt.Fprintf(w, "\n\n\nLabels:")
		for key, value := range attrs.Labels {
			fmt.Fprintf(w, "\t%v = %v\n", key, value)
		}
	}
	return attrs, nil
}

Java

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Acessar no GitHub Feedback

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetBucketMetadata {
  public static void getBucketMetadata(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    // Select all fields. Fields can be selected individually e.g. Storage.BucketField.NAME
    Bucket bucket =
        storage.get(bucketName, Storage.BucketGetOption.fields(Storage.BucketField.values()));

    // Print bucket metadata
    System.out.println("BucketName: " + bucket.getName());
    System.out.println("DefaultEventBasedHold: " + bucket.getDefaultEventBasedHold());
    System.out.println("DefaultKmsKeyName: " + bucket.getDefaultKmsKeyName());
    System.out.println("Id: " + bucket.getGeneratedId());
    System.out.println("IndexPage: " + bucket.getIndexPage());
    System.out.println("Location: " + bucket.getLocation());
    System.out.println("LocationType: " + bucket.getLocationType());
    System.out.println("Metageneration: " + bucket.getMetageneration());
    System.out.println("NotFoundPage: " + bucket.getNotFoundPage());
    System.out.println("RetentionEffectiveTime: " + bucket.getRetentionEffectiveTime());
    System.out.println("RetentionPeriod: " + bucket.getRetentionPeriod());
    System.out.println("RetentionPolicyIsLocked: " + bucket.retentionPolicyIsLocked());
    System.out.println("RequesterPays: " + bucket.requesterPays());
    System.out.println("SelfLink: " + bucket.getSelfLink());
    System.out.println("StorageClass: " + bucket.getStorageClass().name());
    System.out.println("TimeCreated: " + bucket.getCreateTime());
    System.out.println("VersioningEnabled: " + bucket.versioningEnabled());
    if (bucket.getLabels() != null) {
      System.out.println("\n\n\nLabels:");
      for (Map.Entry<String, String> label : bucket.getLabels().entrySet()) {
        System.out.println(label.getKey() + "=" + label.getValue());
      }
    }
    if (bucket.getLifecycleRules() != null) {
      System.out.println("\n\n\nLifecycle Rules:");
      for (BucketInfo.LifecycleRule rule : bucket.getLifecycleRules()) {
        System.out.println(rule);
      }
    }
  }
}

Node.js

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Acessar no GitHub Feedback

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

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

async function getBucketMetadata() {
  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // The ID of your GCS bucket
  // const bucketName = 'your-unique-bucket-name';

  // Get Bucket Metadata
  const [metadata] = await storage.bucket(bucketName).getMetadata();

  console.log(JSON.stringify(metadata, null, 2));
}

PHP

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Acessar no GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Get bucket metadata.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function get_bucket_metadata(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $info = $bucket->info();

    printf('Bucket Metadata: %s' . PHP_EOL, print_r($info));
}

Python

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Acessar no GitHub Feedback

from google.cloud import storage

def bucket_metadata(bucket_name):
    """Prints out a bucket's metadata."""
    # bucket_name = 'your-bucket-name'

    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)

    print(f"ID: {bucket.id}")
    print(f"Name: {bucket.name}")
    print(f"Storage Class: {bucket.storage_class}")
    print(f"Location: {bucket.location}")
    print(f"Location Type: {bucket.location_type}")
    print(f"Cors: {bucket.cors}")
    print(f"Default Event Based Hold: {bucket.default_event_based_hold}")
    print(f"Default KMS Key Name: {bucket.default_kms_key_name}")
    print(f"Metageneration: {bucket.metageneration}")
    print(
        f"Public Access Prevention: {bucket.iam_configuration.public_access_prevention}"
    )
    print(f"Retention Effective Time: {bucket.retention_policy_effective_time}")
    print(f"Retention Period: {bucket.retention_period}")
    print(f"Retention Policy Locked: {bucket.retention_policy_locked}")
    print(f"Requester Pays: {bucket.requester_pays}")
    print(f"Self Link: {bucket.self_link}")
    print(f"Time Created: {bucket.time_created}")
    print(f"Versioning Enabled: {bucket.versioning_enabled}")
    print(f"Labels: {bucket.labels}")

Ruby

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Acessar no GitHub Feedback

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

  require "google/cloud/storage"

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

  puts "ID:                       #{bucket.id}"
  puts "Name:                     #{bucket.name}"
  puts "Storage Class:            #{bucket.storage_class}"
  puts "Location:                 #{bucket.location}"
  puts "Location Type:            #{bucket.location_type}"
  puts "Cors:                     #{bucket.cors}"
  puts "Default Event Based Hold: #{bucket.default_event_based_hold?}"
  puts "Default KMS Key Name:     #{bucket.default_kms_key}"
  puts "Logging Bucket:           #{bucket.logging_bucket}"
  puts "Logging Prefix:           #{bucket.logging_prefix}"
  puts "Metageneration:           #{bucket.metageneration}"
  puts "Retention Effective Time: #{bucket.retention_effective_at}"
  puts "Retention Period:         #{bucket.retention_period}"
  puts "Retention Policy Locked:  #{bucket.retention_policy_locked?}"
  puts "Requester Pays:           #{bucket.requester_pays}"
  puts "Self Link:                #{bucket.api_url}"
  puts "Time Created:             #{bucket.created_at}"
  puts "Versioning Enabled:       #{bucket.versioning?}"
  puts "Index Page:               #{bucket.website_main}"
  puts "Not Found Page:           #{bucket.website_404}"
  puts "Labels:"
  bucket.labels.each do |key, value|
    puts " - #{key} = #{value}"
  end
  puts "Lifecycle Rules:"
  bucket.lifecycle.each do |rule|
    puts "#{rule.action} - #{rule.storage_class} - #{rule.age} - #{rule.matches_storage_class}"
  end
end

Terraform

É possível usar um recurso Terraform para visualizar os metadados de um bucket.

Acessar no GitHub Feedback

# Get bucket metadata
data "google_storage_bucket" "default" {
  name = google_storage_bucket.static.id
}

output "bucket_metadata" {
  value = data.google_storage_bucket.default
}

APIs REST

API JSON

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth. Para ver instruções, consulte Autenticação de APIs.

2. Use cURL (em inglês) para chamar a API JSON com uma solicitação GET Bucket:

   curl -X GET \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME"

   Em que:

   • OAUTH2_TOKEN é o nome do token de acesso que você gerou na etapa 1.
   • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

   Como alternativa, é possível restringir os resultados de metadados usando o parâmetro de string de consulta fields. Exemplo:

   curl -X GET \
   -H "Authorization: Bearer OAUTH2_TOKEN" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=FIELD1%2CFIELD2"

   Em que FIELD# é uma propriedade de bucket que você quer incluir no resultado. Por exemplo, location e storageClass.

A resposta terá esta aparência:

{
  "location": "US",
  "storageClass": "STANDARD"
}

API XML

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth. Para ver instruções, consulte Autenticação de APIs.

2. Use cURL para chamar a API XML com uma solicitação GET bucket:

   curl -X GET \
   -H "Authorization: Bearer OAUTH2_TOKEN" \
   "https://storage.googleapis.com/BUCKET_NAME?QUERY_PARAMETER"

   Em que:

   • OAUTH2_TOKEN é o nome do token de acesso que você gerou na etapa 1.
   • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.
   • QUERY_PARAMETER é o campo de metadados que você quer retornar. Por exemplo, location para receber o local do bucket. Somente é possível usar um parâmetro de consulta por vez com a API XML. Para ver uma lista de campos de metadados compatíveis com a API XML, consulte a página de referência do bucket GET.

   A resposta será parecida com este exemplo: <LocationConstraint>US</LocationConstraint>.

A seguir

• Leia a visão geral dos metadados do bucket.
• Liste os objetos no seu bucket.
• Receber metadados do objeto.
• Altere a classe de armazenamento padrão do seu bucket.
• Saiba mais sobre como monitorar seus recursos no Monitoring.

Faça um teste

Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho do Cloud Storage em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Faça uma avaliação gratuita do Cloud Storage