Elenco degli oggetti

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questa pagina mostra come elencare gli oggetti archiviati nei bucket Cloud Storage, ordinati nell'elenco in base al nome.

Prerequisiti

I prerequisiti possono variare in base allo strumento utilizzato:

Console

Per completare questa guida utilizzando la Google Cloud Console, devi disporre delle autorizzazioni IAM appropriate. Se il bucket a cui vuoi accedere esiste in un progetto che non hai creato, potresti aver bisogno del proprietario del progetto per assegnarti un ruolo contenente le autorizzazioni necessarie.

Per un elenco delle autorizzazioni necessarie per azioni specifiche, consulta le autorizzazioni IAM per la console Google Cloud.

Per un elenco dei ruoli pertinenti, consulta Ruoli di Cloud Storage. In alternativa, puoi creare un ruolo personalizzato con autorizzazioni limitate e specifiche.

Riga di comando

Per completare questa guida utilizzando un'utilità a riga di comando, devi disporre delle autorizzazioni IAM appropriate. Se il bucket a cui vuoi accedere esiste in un progetto che non hai creato, potresti aver bisogno del proprietario del progetto per assegnarti un ruolo contenente le autorizzazioni necessarie.

Per un elenco delle autorizzazioni necessarie per azioni specifiche, consulta le autorizzazioni IAM per i comandi gsutil.

Per un elenco dei ruoli pertinenti, consulta Ruoli di Cloud Storage. In alternativa, puoi creare un ruolo personalizzato con autorizzazioni limitate e specifiche.

Esempi di codice

Per completare questa guida utilizzando le librerie client Cloud Storage, devi disporre delle autorizzazioni IAM appropriate. Se il bucket a cui vuoi accedere esiste in un progetto che non hai creato, potresti aver bisogno del proprietario del progetto per assegnarti un ruolo contenente le autorizzazioni necessarie. Se non diversamente indicato, le richieste della libreria client vengono effettuate tramite l'API JSON.

Per un elenco delle autorizzazioni necessarie per azioni specifiche, consulta le autorizzazioni IAM per i metodi JSON.

Per un elenco dei ruoli pertinenti, consulta Ruoli di Cloud Storage. In alternativa, puoi creare un ruolo personalizzato con autorizzazioni limitate e specifiche.

API REST

API JSON

Per completare questa guida utilizzando l'API JSON, devi disporre delle autorizzazioni IAM appropriate. Se il bucket a cui vuoi accedere esiste in un progetto che non hai creato, potresti aver bisogno del proprietario del progetto per assegnarti un ruolo contenente le autorizzazioni necessarie.

Per un elenco delle autorizzazioni necessarie per azioni specifiche, consulta le autorizzazioni IAM per i metodi JSON.

Per un elenco dei ruoli pertinenti, consulta Ruoli di Cloud Storage. In alternativa, puoi creare un ruolo personalizzato con autorizzazioni limitate e specifiche.

Elencare gli oggetti in un bucket

Completa i passaggi seguenti per elencare gli oggetti in un bucket:

Console

  1. In Google Cloud Console, vai alla pagina Bucket di Cloud Storage.

    Vai a Bucket

  2. Nell'elenco dei bucket, fai clic sul nome del bucket di cui vuoi visualizzare i contenuti.

  3. (Facoltativo) Utilizza i filtri per restringere i risultati nell'elenco.

Riga di comando

gcloud

Utilizza il comando gcloud storage ls con il flag --recursive:

gcloud storage ls --recursive gs://BUCKET_NAME/**

Dove:

  • BUCKET_NAME è il nome del bucket di cui vuoi elencare gli oggetti. Ad esempio, my-bucket.

La risposta sarà simile all'esempio seguente:

gs://my-bucket/cats.jpeg
gs://my-bucket/dogs.jpeg
gs://my-bucket/thesis.txt
...

gsutil

Utilizza il comando gsutil ls con il flag -r:

gsutil ls -r gs://BUCKET_NAME/**

Dove:

  • BUCKET_NAME è il nome del bucket di cui vuoi elencare gli oggetti. Ad esempio, my-bucket.

La risposta sarà simile all'esempio seguente:

gs://my-bucket/cats.jpeg
gs://my-bucket/dogs.jpeg
gs://my-bucket/thesis.txt
...

Esempi di codice

C++

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage C++.

Il seguente esempio elenca tutti gli oggetti in un bucket:

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name) {
  for (auto&& object_metadata : client.ListObjects(bucket_name)) {
    if (!object_metadata) {
      throw std::runtime_error(object_metadata.status().message());
    }

    std::cout << "bucket_name=" << object_metadata->bucket()
              << ", object_name=" << object_metadata->name() << "\n";
  }
}

Il seguente esempio elenca gli oggetti con un determinato prefisso:

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& bucket_prefix) {
  for (auto&& object_metadata :
       client.ListObjects(bucket_name, gcs::Prefix(bucket_prefix))) {
    if (!object_metadata) {
      throw std::runtime_error(object_metadata.status().message());
    }

    std::cout << "bucket_name=" << object_metadata->bucket()
              << ", object_name=" << object_metadata->name() << "\n";
  }
}

C#

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage C#.

Il seguente esempio elenca tutti gli oggetti in un bucket:


using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class ListFilesSample
{
    public IEnumerable<Google.Apis.Storage.v1.Data.Object> ListFiles(
        string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var storageObjects = storage.ListObjects(bucketName);
        Console.WriteLine($"Files in bucket {bucketName}:");
        foreach (var storageObject in storageObjects)
        {
            Console.WriteLine(storageObject.Name);
        }

        return storageObjects;
    }
}

Il seguente esempio elenca gli oggetti con un determinato prefisso:


using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class ListFilesWithPrefixSample
{
    /// <summary>
    /// Prefixes and delimiters can be used to emulate directory listings.
    /// Prefixes can be used to filter objects starting with prefix.
    /// The delimiter argument can be used to restrict the results to only the
    /// objects in the given "directory". Without the delimiter, the entire  tree
    /// under the prefix is returned.
    /// For example, given these objects:
    ///   a/1.txt
    ///   a/b/2.txt
    ///
    /// If you just specify prefix="a/", you'll get back:
    ///   a/1.txt
    ///   a/b/2.txt
    ///
    /// However, if you specify prefix="a/" and delimiter="/", you'll get back:
    ///   a/1.txt
    /// </summary>
    /// <param name="bucketName">The bucket to list the objects from.</param>
    /// <param name="prefix">The prefix to match. Only objects with names that start with this string will
    /// be returned. This parameter may be null or empty, in which case no filtering
    /// is performed.</param>
    /// <param name="delimiter">Used to list in "directory mode". Only objects whose names (aside from the prefix)
    /// do not contain the delimiter will be returned.</param>
    public IEnumerable<Google.Apis.Storage.v1.Data.Object> ListFilesWithPrefix(
        string bucketName = "your-unique-bucket-name",
        string prefix = "your-prefix",
        string delimiter = "your-delimiter")
    {
        var storage = StorageClient.Create();
        var options = new ListObjectsOptions { Delimiter = delimiter };
        var storageObjects = storage.ListObjects(bucketName, prefix, options);
        Console.WriteLine($"Objects in bucket {bucketName} with prefix {prefix}:");
        foreach (var storageObject in storageObjects)
        {
            Console.WriteLine(storageObject.Name);
        }
        return storageObjects;
    }
}

Go

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Go.

Il seguente esempio elenca tutti gli oggetti in un bucket:

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

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

// listFiles lists objects within specified bucket.
func listFiles(w io.Writer, bucket string) error {
	// bucket := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

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

	it := client.Bucket(bucket).Objects(ctx, nil)
	for {
		attrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("Bucket(%q).Objects: %v", bucket, err)
		}
		fmt.Fprintln(w, attrs.Name)
	}
	return nil
}

Il seguente esempio elenca gli oggetti con un determinato prefisso:

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

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

// listFilesWithPrefix lists objects using prefix and delimeter.
func listFilesWithPrefix(w io.Writer, bucket, prefix, delim string) error {
	// bucket := "bucket-name"
	// prefix := "/foo"
	// delim := "_"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	// Prefixes and delimiters can be used to emulate directory listings.
	// Prefixes can be used to filter objects starting with prefix.
	// The delimiter argument can be used to restrict the results to only the
	// objects in the given "directory". Without the delimiter, the entire tree
	// under the prefix is returned.
	//
	// For example, given these blobs:
	//   /a/1.txt
	//   /a/b/2.txt
	//
	// If you just specify prefix="a/", you'll get back:
	//   /a/1.txt
	//   /a/b/2.txt
	//
	// However, if you specify prefix="a/" and delim="/", you'll get back:
	//   /a/1.txt
	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	it := client.Bucket(bucket).Objects(ctx, &storage.Query{
		Prefix:    prefix,
		Delimiter: delim,
	})
	for {
		attrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("Bucket(%q).Objects(): %v", bucket, err)
		}
		fmt.Fprintln(w, attrs.Name)
	}
	return nil
}

Java

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Java.

Il seguente esempio elenca tutti gli oggetti in un bucket:

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

public class ListObjects {
  public static void listObjects(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();
    Page<Blob> blobs = storage.list(bucketName);

    for (Blob blob : blobs.iterateAll()) {
      System.out.println(blob.getName());
    }
  }
}

Il seguente esempio elenca gli oggetti con un determinato prefisso:

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

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

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

    // The directory prefix to search for
    // String directoryPrefix = "myDirectory/"

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    /**
     * Using the Storage.BlobListOption.currentDirectory() option here causes the results to display
     * in a "directory-like" mode, showing what objects are in the directory you've specified, as
     * well as what other directories exist in that directory. For example, given these blobs:
     *
     * <p>a/1.txt a/b/2.txt a/b/3.txt
     *
     * <p>If you specify prefix = "a/" and don't use Storage.BlobListOption.currentDirectory(),
     * you'll get back:
     *
     * <p>a/1.txt a/b/2.txt a/b/3.txt
     *
     * <p>However, if you specify prefix = "a/" and do use
     * Storage.BlobListOption.currentDirectory(), you'll get back:
     *
     * <p>a/1.txt a/b/
     *
     * <p>Because a/1.txt is the only file in the a/ directory and a/b/ is a directory inside the
     * /a/ directory.
     */
    Page<Blob> blobs =
        storage.list(
            bucketName,
            Storage.BlobListOption.prefix(directoryPrefix),
            Storage.BlobListOption.currentDirectory());

    for (Blob blob : blobs.iterateAll()) {
      System.out.println(blob.getName());
    }
  }
}

Node.js

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Node.js.

Il seguente esempio elenca tutti gli oggetti in un bucket:

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

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

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

async function listFiles() {
  // Lists files in the bucket
  const [files] = await storage.bucket(bucketName).getFiles();

  console.log('Files:');
  files.forEach(file => {
    console.log(file.name);
  });
}

listFiles().catch(console.error);

Il seguente esempio elenca gli oggetti con un determinato prefisso:

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

// The directory prefix to search for
// const prefix = 'myDirectory/';

// The delimiter to use
// const delimiter = '/';

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

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

async function listFilesByPrefix() {
  /**
   * This can be used to list all blobs in a "folder", e.g. "public/".
   *
   * The delimiter argument can be used to restrict the results to only the
   * "files" in the given "folder". Without the delimiter, the entire tree under
   * the prefix is returned. For example, given these blobs:
   *
   *   /a/1.txt
   *   /a/b/2.txt
   *
   * If you just specify prefix = 'a/', you'll get back:
   *
   *   /a/1.txt
   *   /a/b/2.txt
   *
   * However, if you specify prefix='a/' and delimiter='/', you'll get back:
   *
   *   /a/1.txt
   */
  const options = {
    prefix: prefix,
  };

  if (delimiter) {
    options.delimiter = delimiter;
  }

  // Lists files in the bucket, filtered by a prefix
  const [files] = await storage.bucket(bucketName).getFiles(options);

  console.log('Files:');
  files.forEach(file => {
    console.log(file.name);
  });
}

listFilesByPrefix().catch(console.error);

PHP

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage PHP.

Il seguente esempio elenca tutti gli oggetti in un bucket:

use Google\Cloud\Storage\StorageClient;

/**
 * List Cloud Storage bucket objects.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 */
function list_objects($bucketName)
{
    // $bucketName = 'my-bucket';

    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    foreach ($bucket->objects() as $object) {
        printf('Object: %s' . PHP_EOL, $object->name());
    }
}

Il seguente esempio elenca gli oggetti con un determinato prefisso:

use Google\Cloud\Storage\StorageClient;

/**
 * List Cloud Storage bucket objects with specified prefix.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 * @param string $directoryPrefix the prefix to use in the list objects API call.
 */
function list_objects_with_prefix($bucketName, $directoryPrefix)
{
    // $bucketName = 'my-bucket';
    // $directoryPrefix = 'myDirectory/';

    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $options = ['prefix' => $directoryPrefix];
    foreach ($bucket->objects($options) as $object) {
        printf('Object: %s' . PHP_EOL, $object->name());
    }
}

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Python.

Il seguente esempio elenca tutti gli oggetti in un bucket:

from google.cloud import storage

def list_blobs(bucket_name):
    """Lists all the blobs in the bucket."""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()

    # Note: Client.list_blobs requires at least package version 1.17.0.
    blobs = storage_client.list_blobs(bucket_name)

    # Note: The call returns a response only when the iterator is consumed.
    for blob in blobs:
        print(blob.name)

Il seguente esempio elenca gli oggetti con un determinato prefisso:

from google.cloud import storage

def list_blobs_with_prefix(bucket_name, prefix, delimiter=None):
    """Lists all the blobs in the bucket that begin with the prefix.

    This can be used to list all blobs in a "folder", e.g. "public/".

    The delimiter argument can be used to restrict the results to only the
    "files" in the given "folder". Without the delimiter, the entire tree under
    the prefix is returned. For example, given these blobs:

        a/1.txt
        a/b/2.txt

    If you specify prefix ='a/', without a delimiter, you'll get back:

        a/1.txt
        a/b/2.txt

    However, if you specify prefix='a/' and delimiter='/', you'll get back
    only the file directly under 'a/':

        a/1.txt

    As part of the response, you'll also get back a blobs.prefixes entity
    that lists the "subfolders" under `a/`:

        a/b/
    """

    storage_client = storage.Client()

    # Note: Client.list_blobs requires at least package version 1.17.0.
    blobs = storage_client.list_blobs(bucket_name, prefix=prefix, delimiter=delimiter)

    # Note: The call returns a response only when the iterator is consumed.
    print("Blobs:")
    for blob in blobs:
        print(blob.name)

    if delimiter:
        print("Prefixes:")
        for prefix in blobs.prefixes:
            print(prefix)

Ruby

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Storage Ruby.

Il seguente esempio elenca tutti gli oggetti in un bucket:

def list_files 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

  bucket.files.each do |file|
    puts file.name
  end
end

Il seguente esempio elenca gli oggetti con un determinato prefisso:

def list_files_with_prefix bucket_name:, prefix:, delimiter: nil
  # Lists all the files in the bucket that begin with the prefix.
  #
  # This can be used to list all files in a "folder", e.g. "public/".
  #
  # The delimiter argument can be used to restrict the results to only the
  # "files" in the given "folder". Without the delimiter, the entire tree under
  # the prefix is returned. For example, given these files:
  #
  #     a/1.txt
  #     a/b/2.txt
  #
  # If you just specify `prefix: "a"`, you will get back:
  #
  #     a/1.txt
  #     a/b/2.txt
  #
  # However, if you specify `prefix: "a"` and `delimiter: "/"`, you will get back:
  #
  #     a/1.txt

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

  # The directory prefix to search for
  # prefix = "a"

  # The delimiter to be used to restrict the results
  # delimiter = "/"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name
  files   = bucket.files prefix: prefix, delimiter: delimiter

  files.each do |file|
    puts file.name
  end
end

API REST

API JSON

  1. Ottieni un token di accesso all'autorizzazione da OAuth 2.0 Playground. Configura l'area giochi in modo che utilizzi le tue credenziali OAuth. Per le istruzioni, consulta Autenticazione API.
  2. Utilizza cURL per chiamare l'API JSON con una GET Bucket richiesta:

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

    Dove:

    • OAUTH2_TOKEN è il token di accesso che hai generato nel passaggio 1.
    • BUCKET_NAME è il nome del bucket di cui vuoi elencare gli oggetti. Ad esempio, my-bucket.

    Puoi utilizzare un parametro stringa di query prefix=PREFIX per limitare i risultati agli oggetti che hanno il prefisso specificato.

API XML

  1. Ottieni un token di accesso all'autorizzazione da OAuth 2.0 Playground. Configura l'area giochi in modo che utilizzi le tue credenziali OAuth. Per le istruzioni, consulta Autenticazione API.
  2. Utilizza cURL per chiamare l'API XML con una GET Bucket richiesta:

    curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" \
      "https://storage.googleapis.com/BUCKET_NAME?list-type=2"

    Dove:

    • OAUTH2_TOKEN è il token di accesso che hai generato nel passaggio 1.
    • BUCKET_NAME è il nome del bucket di cui vuoi elencare gli oggetti. Ad esempio, my-bucket.

    Puoi utilizzare un parametro stringa di query prefix=PREFIX per limitare i risultati agli oggetti che hanno il prefisso specificato.

Passaggi successivi