列出对象

本页面介绍了如何列出 Cloud Storage 存储桶中存储的对象，这些对象按名称的字典顺序在列表中排序。

所需权限

控制台

如需使用 Google Cloud 控制台列出对象，您必须对包含对象的存储桶或父级资源（例如存储桶所属的项目）拥有 storage.objects.list IAM 权限。

您可以通过基本角色、预定义角色或自定义 IAM 角色获取所需权限。如需确定所需的角色，请参阅 Cloud Storage IAM 角色。 如需了解如何授予角色，请参阅使用 IAM。

如需详细了解所需权限，请参阅 Google Cloud 控制台的 Cloud Storage IAM 权限。

命令行

gsutil

重要提示：gsutil 不是推荐用于 Cloud Storage 的 CLI。请改为在 Google Cloud CLI 中使用 gcloud storage 命令。

如需使用 gsutil 列出对象，您必须对包含对象的存储桶或父级资源（例如存储桶所属的项目）拥有 storage.objects.list 权限。如需将对象 ACL 作为列表的一部分返回，您还必须拥有 storage.objects.getIamPolicy 权限。

您可以通过基本角色、预定义角色或自定义 IAM 角色获取所需权限。如需确定所需的角色，请参阅 Cloud Storage IAM 角色。 如需了解如何授予角色，请参阅使用 IAM。

如需详细了解所需权限，请参阅 gsutil 的 Cloud Storage IAM 权限。

gcloud

如需使用 gcloud 列出对象，您必须对包含对象的存储桶或父级资源（例如存储桶所属的项目）拥有 storage.objects.list 权限。如需将对象 ACL 作为列表的一部分返回，您还必须拥有 storage.objects.getIamPolicy 权限。

您可以通过基本角色、预定义角色或自定义 IAM 角色获取所需权限。如需确定所需的角色，请参阅 Cloud Storage IAM 角色。 如需了解如何授予角色，请参阅使用 IAM。

客户端库

如需使用 Cloud Storage 客户端库完成本指南，您必须拥有适当的 IAM 权限。如果您要访问的存储桶在不是由您创建的项目中，则可能需要项目所有者为您提供具有必要权限的角色。

除非另有说明，否则客户端库请求通过 JSON API 发出，并且需要 JSON 方法的 IAM 权限中列出的权限。如需查看使用客户端库发出请求时调用了哪些 JSON API 方法，请记录原始请求。

如需查看相关 IAM 角色的列表，请参阅 Cloud Storage 角色。或者，您也可以创建一个自定义角色，并为其提供具体受限的权限。

REST API

JSON API

如需使用 JSON API 列出对象，您必须对包含对象的存储桶或父级资源（例如存储桶所属的项目）拥有 storage.objects.list 权限。 如需返回对象 ACL，您还必须具有 storage.objects.getIamPolicy 权限。

您可以通过基本角色、预定义角色或自定义 IAM 角色获取所需权限。如需确定所需的角色，请参阅 Cloud Storage IAM 角色。 如需了解如何授予角色，请参阅使用 IAM。

如需详细了解所需权限，请参阅 JSON API 的 Cloud Storage IAM 权限。

列出存储桶中的对象

完成以下步骤以列出存储桶中的对象：

控制台

1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 在存储分区列表中，点击您要查看其内容的存储分区的名称。

3. （可选）使用过滤功能来缩小列表中的结果范围。

命令行

gcloud

将 gcloud storage ls 命令与 --recursive 标志结合使用：

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

其中：

• BUCKET_NAME 是要列出其对象的存储分区的名称，例如 my-bucket。

响应如下例所示：

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

注意：您可以在列表请求中使用前缀，以便将结果限制为具有指定前缀的对象：

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

例如，gcloud storage ls --recursive gs://my-bucket/p** 会返回以下各项：

gs://my-bucket/puppy.png
gs://my-bucket/pug.jpg
gs://my-bucket/pets/dog.png
...

gsutil

重要提示：gsutil 不是推荐用于 Cloud Storage 的 CLI。请改为在 Google Cloud CLI 中使用 gcloud storage 命令。

使用带有 -r 标志的 gsutil ls 命令：

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

其中：

• BUCKET_NAME 是要列出其对象的存储分区的名称，例如 my-bucket。

响应如下例所示：

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

注意：您可以在列表请求中使用前缀，以便将结果限制为具有指定前缀的对象：

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

例如，gsutil ls -r gs://my-bucket/p** 会返回以下各项：

gs://my-bucket/puppy.png
gs://my-bucket/pug.jpg
gs://my-bucket/pets/dog.png
...

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

以下示例会列出存储桶中的所有对象：

在 GitHub 上查看 反馈

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::move(object_metadata).status();

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

以下示例会列出具有给定前缀的对象：

在 GitHub 上查看 反馈

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::move(object_metadata).status();

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

C#

如需了解详情，请参阅 Cloud Storage C# API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

以下示例会列出存储桶中的所有对象：

在 GitHub 上查看 反馈

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

以下示例会列出具有给定前缀的对象：

在 GitHub 上查看 反馈

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

如需了解详情，请参阅 Cloud Storage Go API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

以下示例会列出存储桶中的所有对象：

在 GitHub 上查看 反馈

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: %w", 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: %w", bucket, err)
		}
		fmt.Fprintln(w, attrs.Name)
	}
	return nil
}

以下示例会列出具有给定前缀的对象：

在 GitHub 上查看 反馈

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: %w", 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(): %w", bucket, err)
		}
		fmt.Fprintln(w, attrs.Name)
	}
	return nil
}

Java

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

以下示例会列出存储桶中的所有对象：

在 GitHub 上查看 反馈

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());
    }
  }
}

以下示例会列出具有给定前缀的对象：

在 GitHub 上查看 反馈

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

如需了解详情，请参阅 Cloud Storage Node.js API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

以下示例会列出存储桶中的所有对象：

在 GitHub 上查看 反馈

/**
 * 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);

以下示例会列出具有给定前缀的对象：

在 GitHub 上查看 反馈

/**
 * 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

如需了解详情，请参阅 Cloud Storage PHP API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

以下示例会列出存储桶中的所有对象：

在 GitHub 上查看 反馈

use Google\Cloud\Storage\StorageClient;

/**
 * List Cloud Storage bucket objects.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function list_objects(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    foreach ($bucket->objects() as $object) {
        printf('Object: %s' . PHP_EOL, $object->name());
    }
}

以下示例会列出具有给定前缀的对象：

在 GitHub 上查看 反馈

use Google\Cloud\Storage\StorageClient;

/**
 * List Cloud Storage bucket objects with specified prefix.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $directoryPrefix the prefix to use in the list objects API call.
 *        (e.g. 'myDirectory/')
 */
function list_objects_with_prefix(string $bucketName, string $directoryPrefix): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $options = ['prefix' => $directoryPrefix];
    foreach ($bucket->objects($options) as $object) {
        printf('Object: %s' . PHP_EOL, $object->name());
    }
}

Python

如需了解详情，请参阅 Cloud Storage Python API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

以下示例会列出存储桶中的所有对象：

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)

以下示例会列出具有给定前缀的对象：

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

如需了解详情，请参阅 Cloud Storage Ruby API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

以下示例会列出存储桶中的所有对象：

在 GitHub 上查看 反馈

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

以下示例会列出具有给定前缀的对象：

在 GitHub 上查看 反馈

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

REST API

JSON API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

2. 使用 cURL，通过列出对象的请求调用 JSON API：

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

   其中：

   • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
   • BUCKET_NAME 是要列出其对象的存储分区的名称，例如 my-bucket。

使用 Cloud Storage JSON API 列出对象时，请考虑以下事项：

• 您可以使用 prefix=PREFIX 查询字符串参数将结果限制为仅显示具有指定前缀的对象。

• 您可以使用 matchGlob=GLOB_PATTERN 查询字符串参数过滤结果以仅显示采用特定命名格式的对象。例如，可使用 matchGlob=**.jpeg 来仅显示名称以 .jpeg 结尾的所有对象。

• 如需返回对象 ACL，请将值为 full 的 projection 查询参数附加到请求。请注意，如果对存储桶启用了统一存储桶级访问权限，则系统会停用并无法返回 ACL。

XML API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。如需了解相关说明，请参阅 API 身份验证。

2. 使用 cURL，通过 GET Bucket 请求调用 XML API：

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

   其中：

   • OAUTH2_TOKEN 是您在第 1 步中生成的访问令牌。
   • BUCKET_NAME 是要列出其对象的存储分区的名称，例如 my-bucket。

   您可以使用 prefix=PREFIX 查询字符串参数将结果限制为具有指定前缀的对象。

后续步骤

• 从存储分区下载对象。
• 查看和修改对象元数据。
• 从存储分区中删除对象。
• 了解如何对结果进行分页。