AWS CloudFormation中ApiGatewayV2 Target必填错误及Step Functions集成问题

我正尝试通过AWS CloudFormation构建堆栈，实现Step Functions集成API网关的功能（手动控制台操作已成功），选用ApiGatewayV2是因为它具备RestApi没有的AutoDeploy特性。当前CloudFormation模板配置如下：

GatewayV2:
  Type: AWS::ApiGatewayV2::Api
  Properties:
    Name: !Sub ${AWS::StackName}-GatewayV2
    Description: API Gateway for integrations
    ProtocolType: HTTP
    CredentialsArn: !GetAtt SubmitOrderResourceRole.Arn
    RouteKey: $default
StageV2:
  Type: AWS::ApiGatewayV2::Stage
  Properties:
    ApiId: !Ref GatewayV2
    DeploymentId: !Ref DeploymentV2
    StageName: $default
    AutoDeploy: true
DeploymentV2:
  Type: AWS::ApiGatewayV2::Deployment
  DependsOn:
    - RouteV2
  Properties:
    ApiId: !Ref GatewayV2
    Description: Deployment for the API Gateway
RouteV2:
  Type: AWS::ApiGatewayV2::Route
  Properties:
    ApiId: !Ref GatewayV2
    RouteKey: POST /orders
    Target: !Join
      - /
      - - integrations
        - !Ref IntegrationV2
IntegrationV2:
  Type: AWS::ApiGatewayV2::Integration
  Properties:
    ApiId: !Ref GatewayV2
    IntegrationType: AWS_PROXY
    CredentialsArn: !GetAtt SubmitOrderResourceRole.Arn
    IntegrationMethod: POST
    IntegrationUri: !Sub arn:aws:apigateway:${AWS::Region}:states:action/StartSyncExecution
    PassthroughBehavior: NEVER
    RequestTemplates:
      application/json: !Sub |
        {
          "input": "$util.escapeJavaScript($input.json('$'))",
          "stateMachineArn": "${SubmitOrderStateMachine}"
        }
    ResponseParameters:
      - StatusCode: 200
        ResponseTemplates:
          application/json: |
            if(!$input.json('$.status').toString().equals('"SUCCEEDED"'))
            set($context.responseOverride.status = 500)
            end

部署时收到第一个错误：

Resource handler returned message: "Target is a required property in this context"

尝试在GatewayV2的Target属性中设置Step Function的ARN：

GatewayV2:
  Type: AWS::ApiGatewayV2::Api
  Properties:
    Name: !Sub ${AWS::StackName}-GatewayV2
    Description: API Gateway for integrations
    ProtocolType: HTTP
    CredentialsArn: !GetAtt SubmitOrderResourceRole.Arn
    RouteKey: $default
    Target: !Sub integrations/${SubmitOrderStateMachine}

又收到第二个错误：

Resource handler returned message: "Target only supports HTTP Proxy or Lambda Proxy"

原因分析 #

当你在AWS::ApiGatewayV2::Api资源中指定RouteKey: $default时，API Gateway会自动创建一个默认路由，这个默认路由必须绑定一个Target（集成），因此CloudFormation会强制要求填写Target属性。但这个自动创建的默认路由只支持HTTP Proxy或Lambda Proxy类型的集成，无法直接关联Step Functions，这就是两个错误的根源。

解决方案 #

要绕过这个限制，你需要移除Api资源中的RouteKey配置，避免自动创建默认路由，然后完全手动定义路由、集成、部署和阶段资源。具体修正后的模板如下：

GatewayV2:
  Type: AWS::ApiGatewayV2::Api
  Properties:
    Name: !Sub ${AWS::StackName}-GatewayV2
    Description: API Gateway for integrations
    ProtocolType: HTTP

StageV2:
  Type: AWS::ApiGatewayV2::Stage
  Properties:
    ApiId: !Ref GatewayV2
    DeploymentId: !Ref DeploymentV2
    StageName: $default
    AutoDeploy: true

DeploymentV2:
  Type: AWS::ApiGatewayV2::Deployment
  DependsOn:
    - RouteV2
    - IntegrationV2
  Properties:
    ApiId: !Ref GatewayV2
    Description: Deployment for the API Gateway

RouteV2:
  Type: AWS::ApiGatewayV2::Route
  Properties:
    ApiId: !Ref GatewayV2
    RouteKey: POST /orders
    Target: !Join
      - /
      - - integrations
        - !Ref IntegrationV2
    AuthorizationType: NONE # 根据实际需求调整，比如AWS_IAM

IntegrationV2:
  Type: AWS::ApiGatewayV2::Integration
  Properties:
    ApiId: !Ref GatewayV2
    IntegrationType: AWS_PROXY
    CredentialsArn: !GetAtt SubmitOrderResourceRole.Arn
    IntegrationMethod: POST
    IntegrationUri: !Sub arn:aws:apigateway:${AWS::Region}:states:action/StartSyncExecution
    PassthroughBehavior: NEVER
    RequestTemplates:
      application/json: !Sub |
        {
          "input": "$util.escapeJavaScript($input.json('$'))",
          "stateMachineArn": "${SubmitOrderStateMachine}"
        }
    ResponseParameters:
      - StatusCode: 200
        ResponseTemplates:
          application/json: |
            if(!$input.json('$.status').toString().equals('"SUCCEEDED"'))
            set($context.responseOverride.status = 500)
            end

关键修改说明 #

1. 移除GatewayV2中的RouteKey和CredentialsArn：
   • 去掉RouteKey: $default后，不会自动创建默认路由，也就不再强制要求Target属性
   • Api级别的CredentialsArn移动到集成资源中，更符合权限管控的最佳实践
2. 更新DeploymentV2的依赖：
   • 确保Deployment依赖RouteV2和IntegrationV2，保证部署时路由和集成已完成创建
3. 确认路由配置：
   • 路由的Target正确关联集成ID，格式为integrations/{IntegrationId}
4. AutoDeploy生效：
   • StageV2中AutoDeploy: true会自动触发部署更新，符合你的需求

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