关于Google Cloud Storage JSON REST API访问子目录对象、存储及列表查询的技术咨询

一、访问子目录下的对象：正确的URL构造方式 #

你之前的尝试没成功，核心问题是GCS不存在真正的目录结构——所谓的“子目录”其实是对象名称的一部分（比如foldername/objectname里的foldername/就是前缀）。而HTTP URL里的斜杠会被当成路径分隔符，直接写foldername/objectname会让服务器误解，必须对斜杠进行URL编码（变成%2F）。

正确的API调用URL应该是：

https://storage.googleapis.com/storage/v1/b/bucketname/o/foldername%2Fobjectname?alt=media

更通用的写法是：把完整的对象名称（包含前缀）做URL编码后，替换objectname的位置。比如要访问docs/report.pdf，就把docs%2Freport.pdf放进去。

为什么你的两种尝试失败？

• 第一种https://storage.googleapis.com/storage/v1/b/bucketname/o/foldername/objectname?alt=media：服务器会把foldername/当成API路径的一部分，而非对象名的前缀，自然找不到目标对象。
• 第二种https://storage.googleapis.com/storage/v1/b/bucketname/foldername/o/objectname?alt=media：API的路径结构是固定的/b/{bucket}/o/{object}，bucketname后面不能直接加目录，路径完全不符合规范。

如果用代码实现，记得用语言自带的URL编码函数处理对象名（比如Python的urllib.parse.quote、JavaScript的encodeURIComponent），避免手动编码出错。

二、上传对象到子目录（前缀路径） #

上传逻辑很简单：不需要先“创建目录”，直接把对象的名称设置为包含前缀的路径即可。比如要把文件传到foldername/下，就把对象名设为foldername/objectname。

举个API调用的例子（PUT上传）：

PUT https://storage.googleapis.com/upload/storage/v1/b/bucketname/o?name=foldername%2Fobjectname

请求体里放文件内容，同时带上你的Access Token请求头。如果用gsutil工具，直接执行：

gsutil cp local_file.txt gs://bucketname/foldername/objectname

gsutil会自动处理路径编码，不需要你手动操作。

三、列表查询子目录下的对象 #

要列出某个“子目录”下的对象，你需要用API的prefix和delimiter参数过滤结果：

1. 列出所有以foldername/为前缀的对象（包括子子目录里的）：

GET https://storage.googleapis.com/storage/v1/b/bucketname/o?prefix=foldername/

响应里的items字段会返回所有符合前缀的对象。

2. 模拟“目录”列表（只显示当前目录下的对象和子目录）：
   加上delimiter=/参数，会把相同前缀的子目录（前缀）单独返回，不会递归列出所有子对象：

GET https://storage.googleapis.com/storage/v1/b/bucketname/o?prefix=foldername/&delimiter=/

此时响应里：

• items：当前foldername/下的直接对象（比如foldername/file1.txt）
• prefixes：当前目录下的子目录前缀（比如foldername/subfolder/）

额外注意事项 #

• 确保你的Access Token拥有对应权限：访问需要storage.objects.get，上传需要storage.objects.create，列表需要storage.objects.list。
• GCS里的“目录”只是视觉效果，不存在单独的目录实体——只要有对象带某个前缀，就会在控制台显示为目录；如果删除该前缀下的所有对象，“目录”也会自动消失。

内容的提问来源于stack exchange，提问作者Lucas Stone