如何覆写发送至AWS API Gateway的requestId

API Gateway 对$context.requestId的覆写逻辑不识别请求Query参数、Body字段的传值，仅识别客户端请求携带的AWS预留标准请求头X-Amzn-RequestId，按以下规则操作即可生效：

• 传值格式要求：请求头名称固定为X-Amzn-RequestId（HTTP头本身不区分大小写，按标准写法传即可），头值长度不能超过128字符，仅允许包含大小写英文字母、数字及! # $ % & ' * + - . ^ _ | ~` 这类合法字符，不符合格式要求的头值会被网关直接忽略，自动回退为网关生成的默认requestId。
• 不同API类型的配置说明：
  • REST API 类型：无需额外配置映射模板、无需修改集成设置，客户端发请求时带上符合要求的X-Amzn-RequestId头，后续访问日志、映射模板、后端集成上下文里取$context.requestId，拿到的就是你传入的自定义值；$context.extendedRequestId始终是API Gateway生成的全局唯一不可覆写ID，不受自定义头影响。
  • HTTP API（v2版本）：默认内置该头的识别逻辑，无需额外配置，只要请求链路没有拦截删除该头即可正常覆写。
• 常见失效原因排查：
  • 不要尝试在集成映射模板里手动给$context.requestId赋值，该上下文变量为只读，覆写逻辑只能由客户端传指定请求头触发，模板层面无法修改。
  • 如果链路中配置了WAF、自定义Lambda授权方、CloudFront边缘Lambda@Edge，需要确认上述组件没有过滤删除X-Amzn-RequestId头，头被丢弃后覆写逻辑不会触发。
  • 用API Gateway控制台内置测试功能调试时，需要手动在测试配置的Headers栏添加X-Amzn-RequestId和对应自定义值，控制台默认测试请求不会携带该头，直接测试会看不到覆写效果。

验证生效的最简单方式：配置API Gateway访问日志，同时输出$context.requestId和$context.extendedRequestId字段，携带自定义头发送请求后查看日志，若requestId字段和你传入的头值一致、extendedRequestId为网关生成的独立唯一ID，即说明覆写成功。

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