Enumerar buckets

En esta página, se muestra cómo enumerar los buckets de Cloud Storage de un proyecto, que están ordenados en la lista de forma lexicográfica por nombre.

Antes de comenzar

Para obtener los permisos que necesitas a fin de crear una lista de buckets, pídele a tu administrador que te otorgue el rol de administrador de almacenamiento (roles/storage.admin) o el rol básico de visualizador (roles/viewer) en el proyecto que contiene el proyecto los buckets que deseas enumerar.

Para obtener más información sobre cómo otorgar roles para proyectos, consulta Administra el acceso a los proyectos.

Los roles contienen el permiso storage.buckets.list, que se requiere para enumerar buckets. También puedes obtener este permiso con roles personalizados.

Enumera los buckets de un proyecto

Console

1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.
   

   Ir a Buckets

Los buckets que forman parte del proyecto seleccionado aparecen en la lista.

De manera opcional, usa filtrado y ordenamiento para limitar y organizar los resultados en tu lista.

Línea de comandos

Nota: Cloud Shell aprovisiona una máquina virtual temporal. Si deseas subir objetos a Cloud Storage o descargar objetos de Cloud Storage, usa un entorno de desarrollo local.

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. En tu entorno de desarrollo, ejecuta el comando gcloud storage ls:

   gcloud storage ls

   La respuesta se ve como el siguiente ejemplo:

   gs://BUCKET_NAME1/
     gs://BUCKET_NAME2/
     gs://BUCKET_NAME3/
     ...

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se enumeran todos los buckets disponibles. Si una ubicación no está disponible temporalmente, la respuesta también incluye los nombres de los buckets a los que no se puede acceder.

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client) {
  int count = 0;
  gcs::ListBucketsExtendedReader bucket_list = client.ListBucketsExtended();
  for (auto&& result : bucket_list) {
    if (!result) throw std::move(result).status();

    for (auto const& bucket_metadata : result->buckets) {
      std::cout << bucket_metadata.name() << "\n";
      ++count;
    }
    for (auto const& unreachable : result->unreachable) {
      std::cout << "Unreachable location: " << unreachable << "\n";
    }
  }

  if (count == 0) {
    std::cout << "No buckets in default project\n";
  }
}

En el siguiente ejemplo, se enumeran todos los buckets. Si una ubicación no está disponible temporalmente, el servicio muestra un error.

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client) {
  int count = 0;
  gcs::ListBucketsReader bucket_list = client.ListBuckets();
  for (auto&& bucket_metadata : bucket_list) {
    if (!bucket_metadata) throw std::move(bucket_metadata).status();

    std::cout << bucket_metadata->name() << "\n";
    ++count;
  }

  if (count == 0) {
    std::cout << "No buckets in default project\n";
  }
}

C#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se enumeran todos los buckets disponibles. Si una ubicación no está disponible temporalmente, la respuesta también incluye los nombres de los buckets a los que no se puede acceder.

using Google.Api.Gax;
using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;
using System.Linq;

public class ListBucketsWithPartialSuccessSample
{
    /// <summary>
    /// Lists buckets, returning both the reachable buckets and the resource names of buckets from unreachable locations when specific regions are unreachable.
    /// </summary>
    /// <param name="projectId">The ID of the project to list the buckets.</param>
    public (IReadOnlyList<Bucket> Reachable, IReadOnlyList<string> Unreachable) ListBucketsWithPartialSuccess
        (string projectId = "your-project-id")
    {
        var storage = StorageClient.Create();
        var pagedResult = storage.ListBuckets(projectId, options: new ListBucketsOptions
        {
            ReturnPartialSuccess = true
        });

        var reachableBuckets = new List<Bucket>();
        var unreachableBuckets = new List<string>();

        foreach (var page in pagedResult.AsRawResponses())
        {
            reachableBuckets.AddRange(page.Items ?? Enumerable.Empty<Bucket>());
            unreachableBuckets.AddRange(page.Unreachable ?? Enumerable.Empty<string>());
        }

        Console.WriteLine("Buckets:");
        foreach (var bucket in reachableBuckets)
        {
            Console.WriteLine(bucket.Name);
        }

        if (unreachableBuckets.Any())
        {
            Console.WriteLine("The Resource Names of Buckets from Unreachable Locations:");
            foreach (var bucket in unreachableBuckets)
            {
                Console.WriteLine(bucket);
            }
        }
        return (reachableBuckets, unreachableBuckets);
    }
}

En el siguiente ejemplo, se enumeran todos los buckets. Si una ubicación no está disponible temporalmente, el servicio muestra un error.

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

public class ListBucketsSample
{
    public IEnumerable<Bucket> ListBuckets(string projectId = "your-project-id")
    {
        var storage = StorageClient.Create();
        var buckets = storage.ListBuckets(projectId);
        Console.WriteLine("Buckets:");
        foreach (var bucket in buckets)
        {
            Console.WriteLine(bucket.Name);
        }
        return buckets;
    }
}

Go

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Go.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se enumeran todos los buckets disponibles. Si una ubicación no está disponible temporalmente, la respuesta también incluye los nombres de los buckets a los que no se puede acceder.

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

	"cloud.google.com/go/storage"
	"google.golang.org/api/iterator"
)

// listBucketsPartialSuccess lists buckets in the project. If ReturnPartialSuccess
// is true, the iterator will return reachable buckets and a list of
// unreachable bucket resource names.
func listBucketsPartialSuccess(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

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

	it := client.Buckets(ctx, projectID)
	// Enable returning unreachable buckets.
	it.ReturnPartialSuccess = true

	fmt.Fprintln(w, "Reachable buckets:")
	for {
		battrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			// Errors here usually indicate a problem with the overall list operation
			// or connection, such as a network issue, rather than individual
			// buckets being unreachable. Unreachable buckets due to issues like
			// regional outages or permission issues are typically reported via the
			// Unreachable() method below.
			return err
		}
		fmt.Fprintf(w, "- %v\n", battrs.Name)
	}

	// Retrieve the list of buckets that were unreachable.
	unreachable := it.Unreachable()
	if len(unreachable) > 0 {
		fmt.Fprintln(w, "\nUnreachable buckets:")
		for _, r := range unreachable {
			fmt.Fprintf(w, "- %v\n", r)
		}
	} else {
		fmt.Fprintln(w, "\nNo unreachable buckets.")
	}

	return nil
}

En el siguiente ejemplo, se enumeran todos los buckets. Si una ubicación no está disponible temporalmente, el servicio muestra un error.

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

	"cloud.google.com/go/storage"
	"google.golang.org/api/iterator"
)

// listBuckets lists buckets in the project.
func listBuckets(w io.Writer, projectID string) ([]string, error) {
	// projectID := "my-project-id"
	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*30)
	defer cancel()

	var buckets []string
	it := client.Buckets(ctx, projectID)
	for {
		battrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return nil, err
		}
		buckets = append(buckets, battrs.Name)
		fmt.Fprintf(w, "Bucket: %v\n", battrs.Name)
	}
	return buckets, nil
}

Java

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se enumeran todos los buckets disponibles. Si una ubicación no está disponible temporalmente, la respuesta también incluye los nombres de los buckets a los que no se puede acceder.

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class ListBucketsWithPartialSuccess {
  public static void listBucketsWithPartialSuccess(String projectId) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Page<Bucket> buckets = storage.list(Storage.BucketListOption.returnPartialSuccess(true));

    // Retrieve the list of buckets that are unreachable due to issues like regional outages or
    // permission issues
    System.out.println("Unreachable buckets: \n");
    for (Bucket bucket : buckets.iterateAll()) {
      if (Boolean.TRUE.equals(bucket.isUnreachable())) {
        System.out.println(bucket.getName());
      }
    }
  }
}

En el siguiente ejemplo, se enumeran todos los buckets. Si una ubicación no está disponible temporalmente, el servicio muestra un error.

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class ListBuckets {
  public static void listBuckets(String projectId) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Page<Bucket> buckets = storage.list();

    for (Bucket bucket : buckets.iterateAll()) {
      System.out.println(bucket.getName());
    }
  }
}

Node.js

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se enumeran todos los buckets disponibles. Si una ubicación no está disponible temporalmente, la respuesta también incluye los nombres de los buckets a los que no se puede acceder.

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

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

async function listBucketsPartialSuccess() {
  const option = {
    returnPartialSuccess: true,
    maxResults: 5,
  };
  const [buckets, nextQuery, apiResponse] = await storage.getBuckets(option);

  if (nextQuery && nextQuery.pageToken) {
    console.log(`Next Page Token: ${nextQuery.pageToken}`);
  }

  console.log('\nBuckets:');
  buckets.forEach(bucket => {
    if (bucket.unreachable) {
      console.log(`${bucket.name} (unreachable: ${bucket.unreachable})`);
    } else {
      console.log(`${bucket.name}`);
    }
  });

  if (apiResponse.unreachable && apiResponse.unreachable.length > 0) {
    console.log('\nUnreachable Buckets:');
    apiResponse.unreachable.forEach(item => {
      console.log(item);
    });
  }
}

listBucketsPartialSuccess().catch(console.error);

En el siguiente ejemplo, se enumeran todos los buckets. Si una ubicación no está disponible temporalmente, el servicio muestra un error.

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

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

async function listBuckets() {
  const [buckets] = await storage.getBuckets();

  console.log('Buckets:');
  buckets.forEach(bucket => {
    console.log(bucket.name);
  });
}

listBuckets().catch(console.error);

PHP

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se enumeran todos los buckets disponibles. Si una ubicación no está disponible temporalmente, la respuesta también incluye los nombres de los buckets a los que no se puede acceder.

use Google\Cloud\Storage\StorageClient;

/**
 * Retrieves a list of buckets while gracefully handling regional downtime.
 */
function list_buckets_partial_success(): void
{
    $storage = new StorageClient();
    $options = [ 'returnPartialSuccess' => true ];
    $buckets = $storage->buckets($options);

    // Check for unreachable locations first
    // Note: unreachable() returns an array of strings for buckets in unavailable regions
    if ($unreachable = $buckets->unreachable()) {
        foreach ($unreachable as $location) {
            printf('Unreachable Bucket: %s' . PHP_EOL, $location);
        }
    }

    // Iterate through the buckets that were successfully retrieved
    foreach ($buckets as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

En el siguiente ejemplo, se enumeran todos los buckets. Si una ubicación no está disponible temporalmente, el servicio muestra un error.

use Google\Cloud\Storage\StorageClient;

/**
 * List all Cloud Storage buckets for the current project.
 */
function list_buckets(): void
{
    $storage = new StorageClient();
    foreach ($storage->buckets() as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

Python

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se enumeran todos los buckets disponibles. Si una ubicación no está disponible temporalmente, la respuesta también incluye los nombres de los buckets a los que no se puede acceder.

from google.cloud import storage


def list_buckets_with_partial_success():
    """Lists buckets and includes unreachable buckets in the response."""

    storage_client = storage.Client()

    buckets_iterator = storage_client.list_buckets(return_partial_success=True)

    for page in buckets_iterator.pages:
        if page.unreachable:
            print("Unreachable locations in this page:")
            for location in page.unreachable:
                print(location)

        print("Reachable buckets in this page:")
        for bucket in page:
            print(bucket.name)

En el siguiente ejemplo, se enumeran todos los buckets. Si una ubicación no está disponible temporalmente, el servicio muestra un error.

from google.cloud import storage


def list_buckets():
    """Lists all buckets."""

    storage_client = storage.Client()
    buckets = storage_client.list_buckets()

    for bucket in buckets:
        print(bucket.name)

Ruby

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Ruby.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se enumeran todos los buckets disponibles. Si una ubicación no está disponible temporalmente, la respuesta también incluye los nombres de los buckets a los que no se puede acceder.

# Demonstrates listing Google Cloud Storage buckets with support for partial success.
#
# This method initializes a Google Cloud Storage client and requests a list of buckets.
# When `return_partial_success` is true, the API will return available buckets
# and a list of any buckets that were unreachable.
#
# @param return_partial_success_flag [Boolean] Whether to allow partial success from the API.
#   - true: returns the available buckets and populates `unreachable` with bucket names if any.
#   - false: throws an error if any buckets are unreachable.
def list_buckets_with_partial_success return_partial_success_flag:
  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket_list = storage.buckets return_partial_success: return_partial_success_flag

  puts "Reachable buckets:"
  # limiting the bucket count to be printed to 10 for brevity
  bucket_list.take(10).each do |bucket|
    puts bucket.name
  end

  if bucket_list.unreachable
    puts "\nUnreachable buckets:"
    # limiting the bucket count to be printed to 10 for brevity
    bucket_list.unreachable.take(10).each do |unreachable_bucket_name|
      puts unreachable_bucket_name
    end
  end
end

En el siguiente ejemplo, se enumeran todos los buckets. Si una ubicación no está disponible temporalmente, el servicio muestra un error.

def list_buckets
  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new

  storage.buckets.each do |bucket|
    puts bucket.name
  end
end

API de REST

API de JSON

1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization.

2. Usa cURL para llamar a la API de JSON con una solicitud para enumerar buckets:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/storage/v1/b?project=PROJECT_IDENTIFIER&returnPartialSuccess=RETURN_PARTIAL_SUCCESS_BOOLEAN"

   Reemplaza lo siguiente:

   • PROJECT_IDENTIFIER: Es el ID o el número del proyecto que contiene los buckets que deseas enumerar. Por ejemplo, my-project.
   • RETURN_PARTIAL_SUCCESS_BOOLEAN: Establece este valor en true si deseas devolver una lista de buckets incluso cuando no se pueda acceder a algunos de ellos porque una ubicación no está disponible temporalmente. Si se configura en false, la solicitud devuelve una lista de buckets solo si se puede acceder a todas las ubicaciones. De lo contrario, devuelve un error. El valor predeterminado es false.

API de XML

1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization.

2. Usa cURL para llamar a la API de XML con una solicitud de servicio GET:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-project-id: PROJECT_ID" \
     "https://storage.googleapis.com"

   Reemplaza PROJECT_ID por el ID del proyecto que contiene los buckets que deseas enumerar. Por ejemplo, my-project

¿Qué sigue?

• Obtén información sobre el tamaño de un bucket.
• Enumera los objetos de un bucket.
• Mueve o cambia el nombre de un depósito.
• Borra un bucket.
• Obtén más información sobre cómo paginar resultados.