如何通过AWS API Gateway列出S3存储桶内的所有对象条目

你当前API Gateway与S3的集成仅配置了单对象获取（对应S3原生GetObject接口）的路由规则，请求参数仅绑定了对象key字段，未对接S3的列表查询接口，因此只能访问已知明确key的对象，无法拉取桶内对象清单。

1. 补全API Gateway的IAM执行权限 #

首先给API Gateway绑定的执行角色追加S3列表查询所需的s3:ListBucket权限，否则调用时会返回403权限错误。权限配置参考如下：

{
    "Effect": "Allow",
    "Action": [
        "s3:ListBucket"
    ],
    "Resource": "arn:aws:s3:::你的目标桶名"
}

注意：s3:ListBucket权限的作用范围是桶本身，对应ARN不要加/*后缀，否则权限不生效

2. 配置API Gateway路由与集成映射 #

你可以选两种配置方式，优先选第二种避免影响现有业务：

• 方案一：复用现有/v1/s3/路径，新增参数判断逻辑
  给该路径的GET方法增加条件路由：
  • 当请求携带key查询参数时，保持原有逻辑走S3 GetObject接口，按你现有的规则拆分key值里的桶名和对象名即可，完全兼容现有调用
  • 当请求不携带key查询参数时，转发到S3的ListObjectsV2接口（S3官方推荐的新版列表接口，替代旧版ListObjects）
• 方案二（推荐）：新增独立列表路由
  单独新增/v1/s3/list路径的GET方法，直接对接S3 ListObjectsV2接口，和原有单对象获取逻辑完全隔离，不会影响线上已有业务。

3. 配置列表查询参数映射 #

按需把API Gateway的查询参数映射到S3 ListObjectsV2接口的对应字段，常用参数如下：

• bucket：映射到S3接口的Bucket字段，指定要查询的桶名
• prefix：映射到S3接口的Prefix字段，仅返回指定前缀下的对象，比如传imgs/2024/就只查询该路径下的文件
• max-keys：映射到S3接口的MaxKeys字段，设置单次请求返回的最大条目数，默认值1000
• continuation-token：映射到S3接口的ContinuationToken字段，用于分页查询，当返回结果中存在NextContinuationToken字段时，下次请求传该值即可拉取下一页数据

4. 调用示例 #

配置完成后，原有单对象获取逻辑完全不变，调用方式和你现在用的一致：

https://awsdomain/v1/s3/?key=name-bucket%2Fname-object

列表查询调用示例：

# 查询桶内全量对象
https://awsdomain/v1/s3/list?bucket=name-bucket

# 查询桶内指定前缀下的对象，单次返回20条
https://awsdomain/v1/s3/list?bucket=name-bucket&prefix=imgs%2F&max-keys=20

注意事项 #

• 不要把无鉴权的列表查询接口直接暴露在公网，建议搭配API Key、IAM授权或自定义作者器做访问控制，避免桶内资源被恶意遍历爬取
• 当桶内对象数量超过max-keys设置值时，返回结果会带IsTruncated: true标记，需要循环传入continuation-token拉取全量数据
• 如果需要JSON格式的返回结果，可以在API Gateway里配置响应映射模板，把S3默认返回的XML格式直接转换为JSON，减少前端处理成本

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