本页面介绍了如何列出 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 政策。
列出存储桶中的对象
控制台
- 在 Google Cloud 控制台中,转到 Cloud Storage 存储桶页面。
在存储桶列表中,点击您要查看其内容的存储桶的名称。
命令行
使用 gcloud storage ls
命令:
gcloud storage ls gs://BUCKET_NAME
其中:
BUCKET_NAME
是包含要列出的对象的存储桶的名称。例如my-bucket
。
客户端库
C++
如需了解详情,请参阅 Cloud Storage C++ API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
以下示例会列出存储桶中的所有对象:
以下示例会列出具有给定前缀的对象:
C#
如需了解详情,请参阅 Cloud Storage C# API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
以下示例会列出存储桶中的所有对象:
以下示例会列出具有给定前缀的对象:
Go
如需了解详情,请参阅 Cloud Storage Go API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
以下示例会列出存储桶中的所有对象:
以下示例会列出具有给定前缀的对象:
Java
如需了解详情,请参阅 Cloud Storage Java API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
以下示例会列出存储桶中的所有对象:
以下示例会列出具有给定前缀的对象:
Node.js
如需了解详情,请参阅 Cloud Storage Node.js API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
以下示例会列出存储桶中的所有对象:
以下示例会列出具有给定前缀的对象:
PHP
如需了解详情,请参阅 Cloud Storage PHP API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
以下示例会列出存储桶中的所有对象:
以下示例会列出具有给定前缀的对象:
Python
如需了解详情,请参阅 Cloud Storage Python API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
以下示例会列出存储桶中的所有对象:
以下示例会列出具有给定前缀的对象:
Ruby
如需了解详情,请参阅 Cloud Storage Ruby API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
以下示例会列出存储桶中的所有对象:
以下示例会列出具有给定前缀的对象:
REST API
JSON API
XML API
安装并初始化 gcloud CLI,以便为
Authorization
标头生成访问令牌。使用
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
查询字符串参数将结果限制为具有指定前缀的对象。
列出文件夹中的对象
控制台
- 在 Google Cloud 控制台中,转到 Cloud Storage 存储桶页面。
在存储桶列表中,点击包含相应文件夹的存储桶的名称。
在存储桶详情页面的对象标签页中,点击您要查看其内容的文件夹的名称。
命令行
使用 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/
。
过滤对象
列出对象时,您可以在列表请求中使用前缀或后缀按名称过滤对象。
控制台
如需了解如何过滤和排序存储桶或文件夹中的对象,请参阅过滤和排序。
命令行
您可以在 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
如需了解如何按文件夹或对象名称前缀过滤对象,请参阅列出文件夹中的对象。
按对象上下文过滤
您可以使用 filter
查询参数来仅显示响应的 items[]
数组中具有指定上下文 (预览) 的对象。
以下 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 支持以下 filter
查询参数语法:
语法 | 说明 |
---|---|
contexts."KEY":* |
匹配附加了具有指定键的上下文的任何对象。 |
contexts."KEY"="VALUE" |
匹配附加了具有指定键和值的上下文的任何对象。 |
OR
|
匹配任何未附加具有指定键的上下文的对象。 |
OR
|
匹配未附加具有指定键和值的上下文的任何对象。 |
列出对象时的性能注意事项
与平面命名空间存储桶相比,启用了分层命名空间的存储桶的底层结构会影响列出对象操作的性能。如需了解详情,请参阅在启用了分层命名空间的存储桶中优化性能。
后续步骤
- 从存储桶下载对象。
- 查看和修改对象元数据。
- 从存储桶中删除对象。
- 了解如何对结果进行分页。