使用Postman调用API PUT请求时Amazon S3对象元数据未更新

1. 关键配置：API Gateway集成请求的头映射 #

这是最容易遗漏的核心步骤——API Gateway不会自动转发x-amz-meta-开头的请求头到S3，必须手动配置映射：

• 打开API Gateway控制台，找到你的上传API和对应的POST方法
• 进入「集成请求」页面，找到「HTTP头」区域
• 添加映射规则：
  • 若要固定某个元数据（比如x-amz-meta-userid）：名称填x-amz-meta-userid，映射值填method.request.header.x-amz-meta-userid
  • 若要支持任意自定义元数据，添加通配符映射：名称填x-amz-meta-*，映射值填method.request.header.x-amz-meta-*
• 保存配置后，必须重新部署API到对应阶段，否则修改不会生效

2. 正确传递元数据的两种方式 #

方式一：通过请求头传递 #

在Postman的「Headers」标签中直接添加x-amz-meta-{key}格式的头，比如：

• 键：x-amz-meta-description
• 值：用户上传的头像
  注意：头名称必须严格以x-amz-meta-开头，S3才会将其识别为自定义元数据。

方式二：通过form-data字段传递（针对多表单上传） #

如果你的请求是multipart/form-data格式，需要在映射模板里把form字段映射为S3元数据头：

• 在集成请求的「映射模板」中，选择multipart/form-data类型，添加如下示例模板：

{
  "headers": {
    "x-amz-meta-userid": "$input.params('userid')",
    "x-amz-meta-tag": "$input.params('tag')"
  }
}

然后在Postman的「Body」-「form-data」中添加userid、tag等字段，对应的值会被自动映射为S3对象的自定义元数据。

3. 权限与CORS检查 #

• 确认API Gateway的执行角色拥有s3:PutObject权限，且策略中未限制x-amz-meta-*头的传递（默认PutObject权限允许，若有自定义策略需确保包含相关允许项）
• 检查S3桶的CORS配置，确保允许x-amz-meta-*头，示例CORS规则：

<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>*</AllowedOrigin>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedHeader>x-amz-meta-*</AllowedHeader>
    <AllowedHeader>content-type</AllowedHeader>
  </CORSRule>
</CORSConfiguration>

4. 验证与排查 #

• 部署API后，重新用Postman发送请求，然后到S3控制台查看对象的「元数据」标签，确认自定义项是否存在
• 若仍不生效，开启API Gateway的访问日志，查看集成请求阶段是否正确转发了x-amz-meta-头到S3

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