AWS API Gateway调用Step Functions无法传递x-api-key头部问题

核心前提 #

Step Functions的StartExecution接口要求input参数必须是合法的JSON字符串，而非直接传入JSON对象，这是避免序列化报错的关键。

正确的VTL映射模板写法 #

通过VTL合并请求体与x-api-key头部，再转义为符合要求的JSON字符串：

#set($requestBody = $input.json('$'))
#set($apiKeyData = {"x-api-key": "$context.requestIdentity.apiKey"})
#set($combinedInput = $requestBody.merge($apiKeyData))
{
  "input": "$util.escapeJavaScript($combinedInput)",
  "stateMachineArn": "arn:aws:states:你的区域:你的账号ID:stateMachine:你的状态机名称"
}

• $context.requestIdentity.apiKey：直接获取请求头中的x-api-key值
• $util.escapeJavaScript：将合并后的JSON对象转义为字符串，匹配StartExecution对input参数的格式要求
• merge方法：将请求体与x-api-key对象合并为一个完整的输入结构

常见错误排查 #

• 序列化报错根源：未将合并后的JSON对象转义为字符串，直接赋值给input字段，导致API Gateway调用StartExecution时无法正确序列化参数。
• 模板语法问题：检查VTL指令的引号转义、变量定义是否合法，比如字符串中的双引号需正确处理。

验证步骤 #

1. 在API Gateway测试控制台发送请求，查看集成请求的输出结构，确认input字段是转义后的完整JSON字符串。
2. 查看Step Functions的执行历史，检查输入参数是否同时包含请求体内容与x-api-key字段。

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