如何为AWS::Serverless::Api配置角色以查看API网关错误日志？

问题根源 #

AWS::Serverless::Api 资源本身没有顶层的 Role 属性，你直接在Properties里添加Role会导致CloudFormation识别失败，这就是编辑器提示"Unknown resource type property: Role"以及变更集创建失败的原因。要为API网关配置日志角色，需要通过阶段（Stage）的访问日志设置来关联IAM角色。

正确配置方式 #

以下两种方法都可以实现为API网关配置CloudWatch日志角色：

方法一：通过SAM的StageSettings配置

在AWS::Serverless::Api的StageSettings中添加AccessLogSetting，指定日志格式和IAM角色ARN：

MyApiGateway:
  Type: AWS::Serverless::Api
  Properties:
    Name:
      !Sub
      - '${TheEnv}-${TheAppNameForResources}-api'
      - TheEnv: !Ref Environment
        TheAppNameForResources: !Ref AppNameForResources
    TracingEnabled: true
    OpenApiVersion: 3.0.2
    Cors:
      AllowHeaders: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'"
      AllowMethods: "'*'"
      AllowOrigin: "'*'"
    StageName: test
    # 新增StageSettings配置访问日志
    StageSettings:
      AccessLogSetting:
        DestinationArn: !Sub 'arn:aws:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/api-gateway/${MyApiGateway}'
        Format: '{"requestId":"$context.requestId","ip":"$context.identity.sourceIp","caller":"$context.identity.caller","user":"$context.identity.user","requestTime":"$context.requestTime","httpMethod":"$context.httpMethod","resourcePath":"$context.resourcePath","status":"$context.status","protocol":"$context.protocol","responseLength":"$context.responseLength"}'
        IamRoleArn: !GetAtt APICloudwatchLogRole.Arn
    DefinitionBody:
      swagger: "2.0"
      paths:
        /batch:
          get:
            x-amazon-apigateway-integration:
              uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${MyLambdaFunction.Arn}/invocations
              httpMethod: GET
              type: "aws_proxy"

方法二：在DefinitionBody的Swagger/OpenAPI定义中配置

如果需要通过Swagger定义来设置，可以在DefinitionBody的x-amazon-apigateway-stage扩展里添加访问日志设置：

MyApiGateway:
  Type: AWS::Serverless::Api
  Properties:
    Name:
      !Sub
      - '${TheEnv}-${TheAppNameForResources}-api'
      - TheEnv: !Ref Environment
        TheAppNameForResources: !Ref AppNameForResources
    TracingEnabled: true
    OpenApiVersion: 3.0.2
    Cors:
      AllowHeaders: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'"
      AllowMethods: "'*'"
      AllowOrigin: "'*'"
    StageName: test
    DefinitionBody:
      swagger: "2.0"
      # 添加x-amazon-apigateway-stage配置访问日志
      x-amazon-apigateway-stage:
        accessLogSetting:
          destinationArn: !Sub 'arn:aws:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/api-gateway/${MyApiGateway}'
          format: '{"requestId":"$context.requestId","ip":"$context.identity.sourceIp","caller":"$context.identity.caller","user":"$context.identity.user","requestTime":"$context.requestTime","httpMethod":"$context.httpMethod","resourcePath":"$context.resourcePath","status":"$context.status","protocol":"$context.protocol","responseLength":"$context.responseLength"}'
          iamRoleArn: !GetAtt APICloudwatchLogRole.Arn
      paths:
        /batch:
          get:
            x-amazon-apigateway-integration:
              uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${MyLambdaFunction.Arn}/invocations
              httpMethod: GET
              type: "aws_proxy"

注意事项 #

• 你的APICloudwatchLogRole角色配置是正确的，信任策略允许apigateway.amazonaws.com扮演该角色，且权限包含CloudWatch日志的创建和写入操作，无需修改。
• 确保你的SAM模板开头的Transform: AWS::Serverless-2016-10-31（或更高版本）已正确声明，新版本SAM支持上述配置属性。
• 日志组如果不存在，API网关会自动创建，但需要角色有logs:CreateLogGroup权限（你的角色已包含）。

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