如何用YAML创建Step Functions StateMachine的CloudFormation资源及API调用配置

背景 #

我已在控制台创建了可正常运行的Step Function，希望通过CloudFormation（CFT）部署相同功能，但未找到仅通过定义创建StateMachine的清晰示例。理想情况下，我希望能通过API Gateway调用该Step Function并在调用时传递参数。现有如下CloudFormation代码，并提出三个问题：

RandomSM:
  Type: "AWS::StepFunctions::StateMachine"
  Properties:
    StateMachineName: !Join ["", ["RandomStateMachine1-" , !FindInMap [StageMap, !Ref Stage, ENV]]]
    RoleArn: !Sub 'arn:aws:iam::customLambdaRole'
    StateMachineType: STANDARD
    DefinitionString: !Sub {"StartAt":"RandomStateMachine1","States":{"RandomStateMachine1":{"Type":"Task","Resource":"arn:aws:states:::lambda:invoke","Parameters":{"FunctionName":"arn:aws:lambda:us-east-1:RandomStateMachine1-dev:$LATEST","Payload.$":"$"},"Retry":[{"ErrorEquals":["Lambda.ServiceException","Lambda.AWSLambdaException","Lambda.SdkClientException","Lambda.TooManyRequestsException"],"IntervalSeconds":1,"MaxAttempts":1,"BackoffRate":1}],"ResultSelector":{"start_date.$":"$.Payload.body.payload[0]","end_date.$":"$.Payload.body.payload.[1]","previous_iteration.$":"$.Payload.body.payload[2]","row_count.$":"$.Payload.body.payload[3]","httpMethod.$":"$.Payload.body.payload[4]"},

"Next":"RandomStateMachine2"},"RandomStateMachine2":{"Type":"Task","Resource":"arn:aws:states:::lambda:invoke","Parameters":{"Payload.$":"$","FunctionName":"arn:aws:lambda:us-east-1:RandomStateMachine2Function-dev:$LATEST"},"Retry":[{"ErrorEquals":["Lambda.ServiceException","Lambda.AWSLambdaException","Lambda.SdkClientException","Lambda.TooManyRequestsException"],"IntervalSeconds":1,"MaxAttempts":1,"BackoffRate":1}],"ResultSelector":{"start_date.$":"$.Payload.body.payload[0]","end_date.$":"$.Payload.body.payload.[1]","previous_iteration.$":"$.Payload.body.payload[2]","row_count.$":"$.Payload.body.payload[3]","httpMethod.$":"$.Payload.body.payload[4]"},

"Next":"Excess Records?"},"Excess Records?":{"Type":"Choice","Choices":[{"Variable":"$.previous_iteration","NumericEquals":0,"Next":"Pass"},{"Not":{"Variable":"$.previous_iteration","NumericEquals":0},"Next":"RandomStateMachine2"}]},"Pass":{"Type":"Pass","End":true}}}

问题与解答 #

问题1：是否需要将所有"$.variable.otherVariable"格式的内容替换为${variable.otherVariable}？ #

不需要。$.variable.otherVariable是Step Functions的JSONPath语法，用于状态机运行时引用执行数据；而${...}是CloudFormation的模板变量替换语法，仅在部署阶段生效。两者完全独立，把JSONPath改成CloudFormation变量格式会导致状态机运行时无法识别数据路径，直接报错。

问题2：是否需要对这些值的键也执行同样的替换操作？ #

完全不需要。键中的. $后缀（比如start_date.$）是Step Functions的特殊标记，用来声明该值是通过JSONPath动态获取的，而非静态字符串。修改这些键会破坏状态机的语法规则，导致定义失效。

问题3：如何为Step Function配置API Gateway路径，该配置方式是否与Lambda的配置方式相同？ #

配置逻辑和Lambda类似，但有几个核心差异：

• 集成类型选择：在API Gateway中创建AWS Service类型的集成，目标服务选Step Functions，动作指定为StartExecution。
• 权限配置：给API Gateway的执行角色添加states:StartExecution权限，允许其调用你的目标状态机。
• 请求映射模板：需要把API Gateway的请求参数转换成Step FunctionsStartExecution所需的格式，示例VTL模板如下：

{
  "input": "$util.escapeJavaScript($input.json('$'))",
  "stateMachineArn": "arn:aws:states:us-east-1:${AWS::AccountId}:stateMachine:RandomStateMachine1-!FindInMap [StageMap, !Ref Stage, ENV]"
}

• 路径配置：和Lambda一样，你可以自定义API路径（比如/run-state-machine），将该路径与Step Functions的集成绑定即可。

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