列出对象

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

准备工作

如需获得列出对象所需的权限，请让您的管理员向您授予包含待列出对象的存储桶的 Storage Object Viewer (roles/storage.objectViewer) IAM 角色。 如果您想列出托管文件夹中的对象，可以向包含要查看的对象的托管文件夹授予 roles/storage.objectViewer，而不是向存储桶授予。

如果您计划使用 Google Cloud 控制台执行本页面上的任务，请让您的管理员授予您 Viewer (roles/viewer) 基本角色，以及 Storage Object Viewer (roles/storage.objectViewer) 角色。

这些角色包含列出对象所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

• storage.objects.list
• storage.buckets.list
  • 仅当您要使用 Google Cloud 控制台执行本页面上的任务时，才需要此权限。

您也可以通过其他预定义角色或自定义角色获取这些权限。

如需了解如何授予存储桶的角色，请参阅设置和管理存储桶的 IAM 政策。

列出存储桶中的对象

控制台

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

   进入“存储桶”

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

命令行

使用 gcloud storage ls 命令：

gcloud storage ls gs://BUCKET_NAME

其中：

• BUCKET_NAME 是包含要列出的对象的存储桶的名称。例如 my-bucket。

客户端库

C++

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

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

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

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

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 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

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

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

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 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

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
}

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

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 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

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

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

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 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

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

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

/**
 * 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 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

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

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

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/


    Note: If you only want to list prefixes a/b/ and don't want to iterate over
    blobs, you can do

    ```
    for page in blobs.pages:
        print(page.prefixes)
    ```
    """

    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 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

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

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

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. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

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

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o"

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

XML API

1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

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

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/BUCKET_NAME?list-type=2"

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

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

列出文件夹中的对象

控制台

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

   进入“存储桶”

2. 在存储桶列表中，点击包含相应文件夹的存储桶的名称。

3. 在存储桶详情页面的对象标签页中，点击您要查看其内容的文件夹的名称。

命令行

使用 gcloud storage ls 命令列出文件夹中的对象：

gcloud storage ls gs://BUCKET_NAME/FOLDER_NAME

其中：

• BUCKET_NAME 是包含相应文件夹的存储桶的名称。例如 my-bucket。

• FOLDER_NAME 是包含要列出的对象的文件夹的名称。例如 my-folder。

REST API

JSON API

如需列出文件夹中的对象，请使用包含 prefix 和 delimiter 参数的列出对象请求。设置 prefix 参数后，列表操作的范围将限定为仅返回具有相应前缀的对象和文件夹。设置 delimiter 参数后，响应中的 prefixes[] 列表会填充指定前缀下的文件夹名称。

例如：

• 如需列出存储桶 my-bucket 中文件夹 image/ 内的所有对象，请使用以下网址："https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image&delimiter=/"。

  这可能会返回对象 my-bucket/image/cat.jpeg 和 my-bucket/image/dog.jpeg。

• 如需包含 image/ 内子文件夹中的对象，请移除 delimiter 参数："https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image"。

  这可能会返回对象 my-bucket/image/cat.jpeg、my-bucket/image/dog.jpeg 和 my-bucket/image/dog/shiba.jpeg。

如需在列出对象的请求中使用通配符，并按 glob 表达式匹配对象，请使用 matchGlob 参数。例如，matchGlob=**.jpeg 会匹配以 .jpeg 结尾的所有对象。使用 matchGlob 时，您必须将 delimiter 设置为 /。

例如，使用以下网址可匹配文件夹 image 中以 .jpeg 结尾的所有对象： "https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image&delimiter=/&matchGlob=**.jpeg"

如需详细了解如何使用参数来过滤对象，请参阅对象列出 JSON API 参考文档。

使用场景

如果您仅拥有列出文件夹中对象的权限，而没有列出整个存储桶中对象的权限，则使用 prefix 列出文件夹的内容非常有用。例如，假设您拥有托管式文件夹 my-bucket/my-managed-folder-a/ 的 Storage Object Viewer (roles/storage.objectViewer) IAM 角色，但没有托管式文件夹 my-bucket/my-managed-folder-b/ 的相应角色。如需仅返回 my-managed-folder-a 中的对象，您可以指定 prefix=my-managed-folder-a/。

注意：托管式文件夹过滤时，请将 includeFoldersAsPrefixes 参数设置为 true，并将 delimiter 参数设置为 /。

过滤对象

列出对象时，您可以在列表请求中使用前缀或后缀按名称过滤对象。

控制台

如需了解如何过滤和排序存储桶或文件夹中的对象，请参阅过滤和排序。

命令行

您可以在 gcloud storage ls 命令中使用通配符，按前缀或后缀过滤对象。例如，以下命令仅列出存储桶 my-bucket 中名称以 image 开头并以 .png 结尾的对象：

gcloud storage ls gs://my-bucket/image*.png

如果请求成功，则响应类似于以下内容：

gs://my-bucket/image.png
gs://my-bucket/image-dog.png
gs://my-bucket/image-cat.png
...

您可以使用双星号通配符来匹配路径中的零个或多个文件夹级别。例如，以下命令仅列出存储桶 my-bucket 内任何文件夹或子文件夹中名称以 .jpeg 结尾的对象：

gcloud storage ls gs://my-bucket/**/*.jpeg

如果请求成功，则响应类似于以下内容：

gs://my-bucket/puppy.jpeg
gs://my-bucket/pug.jpeg
gs://my-bucket/pets/dog.jpeg
...

REST API

如需了解如何按文件夹或对象名称前缀过滤对象，请参阅列出文件夹中的对象。

按上下文过滤对象

您可以使用过滤条件，仅在列表响应中显示具有指定上下文（预览版）的对象。

命令行

使用 gcloud alpha storage objects list 命令：

gcloud alpha storage objects list gs://BUCKET_NAME --metadata-filter='contexts."KEY"="VALUE"'

其中：

• BUCKET_NAME 是包含要按上下文过滤的对象的存储桶的名称。例如 my-bucket。
• KEY 是附加到对象的上下文键。
• VALUE 是与上下文键关联的值。

如果成功，响应类似于以下示例：

---
bucket: my-bucket
contexts:
  Department:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: HR
  DataClassification:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Confidential
name: employees.txt
...

注意： 如需将输出限制为仅包含上下文键和值，请使用 --format=contextsonly。

客户端库

Java

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

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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 ListObjectContexts {
  public static void listObjectContexts(String projectId, String bucketName, String key)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

    // The context key you want to filter
    // String key = "your-context-key";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {
      /*
       * List any object that has a context with the specified key attached
       * String filter = "contexts.\"KEY\":*";
       *
       * List any object that that does not have a context with the specified key attached
       * String filter = "NOT contexts.\"KEY\":*";
       *
       * List any object that has a context with the specified key and value attached
       * String filter = "contexts.\"KEY\"=\"VALUE\"";
       *
       * List any object that does not have a context with the specified key and value attached
       * String filter = "NOT contexts.\"KEY\"=\"VALUE\"";
       */

      String filter = "contexts.\"" + key + "\":*";

      System.out.println("Listing objects for bucket: " + bucketName + "with context key: " + key);
      Page<Blob> blobs = storage.list(bucketName, Storage.BlobListOption.filter(filter));
      for (Blob blob : blobs.iterateAll()) {
        System.out.println(blob.getBlobId().toGsUtilUri());
      }
    }
  }
}

REST API

JSON API

以下 Object: list 请求展示了如何使用 filter 查询参数：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/?filter=contexts.%22KEY%22%3D%22VALUE%22"

其中：

• BUCKET_NAME 是包含要按上下文过滤的对象的存储桶的名称。例如 my-bucket。
• KEY 是附加到对象的上下文键。
• VALUE 是与上下文键关联的值。

语法

Cloud Storage 支持以下过滤条件语法。

语法	说明
contexts."KEY":*	匹配附加了具有指定键的上下文的任何对象。
contexts."KEY"="VALUE"	匹配附加了具有指定键和值的上下文的任何对象。
NOT contexts."KEY":* OR -contexts."KEY":*	匹配任何未附加具有指定键的上下文的对象。
NOT contexts."KEY"="VALUE" OR -contexts."KEY"="VALUE"	匹配未附加具有指定键和值的上下文的任何对象。

列出对象时的性能注意事项

与平面命名空间存储桶相比，启用了分层命名空间的存储桶的底层结构会影响列出对象操作的性能。如需了解详情，请参阅在启用了分层命名空间的存储桶中优化性能。

后续步骤

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