AWS::Serverless::HttpApi

创建API网关HTTPAPI,使您能够创建 RESTful APIs 相比REST具有更低的延迟和更低的成本 APIs。有关HTTP的更多信息 APIs 参见 HTTPAPI(HTTPAPI) 在 API 网关开发人员指南.

语法

若要在您的 AWS 无服务器应用程序模型 (AWS SAM)模板,请使用以下语法。

YAML


Type: AWS::Serverless::HttpApi
Properties:
  AccessLogSettings: AccessLogSettings
  Auth: HttpApiAuth
  CorsConfiguration: String | HttpApiCorsConfiguration
  DefaultRouteSettings: RouteSettings
  DefinitionBody: String
  DefinitionUri: String | HttpApiDefinition
  Domain: HttpApiDomainConfiguration
  FailOnWarnings: Boolean
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

属性

AccessLogSettings

某个阶段的访问日志记录的设置。

类型: AccessLogSettings

必需: 否

AWS CloudFormation 兼容性: 此属性直接传递到 AccessLogSettings 属性 AWS::ApiGatewayV2::Stage 资源。

Auth

配置授权以控制对您的的访问 API 网关 API。

有关配置访问的更多信息,请参阅 JWT授权者在 API 网关开发者指南.

类型: HttpApiAuth

必需: 否

AWS CloudFormation 兼容性: 此属性是 AWS SAM 并且没有 AWS CloudFormation 等效。

CorsConfiguration

管理所有HTTP的跨源资源共享(CORS) APIs。指定域以允许作为字符串或指定具有其他Cors配置的字典。注意：CORS需要 AWS SAM 修改您的 OpenAPI 定义。因此,它只能在线运行 OpenApi 使用 DefinitionBody.

有关CORS的更多信息,请参阅为HTTPAPI配置CORS 的AmazonAPIGatewayDeveloperGuide中。

注意：如果 CorsConfiguration 都设定于 OpenAPI 在酒店层面, AWS SAM 将其与属性合并,属性优先。

注意：如果此属性设置为 True 则允许所有起运地。

类型:字符串| HttpApiCorsConfiguration

必需: 否

AWS CloudFormation 兼容性: 此属性是 AWS SAM 并且没有 AWS CloudFormation 等效。

DefaultRouteSettings

此HTTPAPI的默认路由设置。这些设置适用于所有路由,除非被 RouteSettings 属性。

类型: RouteSettings

必需: 否

AWS CloudFormation 兼容性: 此属性直接传递到 RouteSettings 属性 AWS::ApiGatewayV2::Stage 资源。

DefinitionBody

OpenAPI 描述您的API的规范。如果两者都不是 DefinitionUri 或 DefinitionBody 指定,SAM将生成 DefinitionBody 根据您的模板配置。

类型：字符串

必需: 否

AWS CloudFormation 兼容性: 该属性类似于 Body 属性 AWS::ApiGatewayV2::Api 资源。如果提供了某些属性,则可以在 DefinitionBody 之后再转到 CloudFormation。属性包括 Auth 以及 EventSource 类型 HttpApi 对应 AWS::Serverless::Function.

DefinitionUri

AWSS3Uri、本地文件路径或 OpenAPI 定义API的文档。此属性引用的AWSS3对象必须是有效的 OpenAPI 文件。如果两者都不是 DefinitionUri 或 DefinitionBody 指定,SAM将生成 DefinitionBody 根据您的模板配置。

如果提供了本地文件路径,则模板必须通过包含 sam deploy 或 sam package 命令,以便正确转换定义。

外部不支持内部函数 OpenApi 文件引用者 DefinitionUri。使用 DefinitionBody 属性,带有包括转换以导入 OpenApi 定义到模板中。

类型:字符串| HttpApiDefinition

必需: 否

AWS CloudFormation 兼容性: 该属性类似于 BodyS3Location 属性 AWS::ApiGatewayV2::Api 资源。嵌套 Amazon S3 属性的名称不同。

Domain

配置此的自定义域 API 网关 API。

类型: HttpApiDomainConfiguration

必需: 否

AWS CloudFormation 兼容性: 此属性是 AWS SAM 并且没有 AWS CloudFormation 等效。

FailOnWarnings

指定在遇到警告时是否回滚API创建(是)或(否)。默认值为 false。

类型：布尔值

必需: 否

AWS CloudFormation 兼容性: 此属性直接传递到 FailOnWarnings 属性 AWS::ApiGatewayV2::Api 资源。

RouteSettings

此HTTPAPI的按路由路由设置。有关路由设置的更多信息,请参阅 AWS::ApiGatewayV2::阶段 RouteSettings 在 API 网关开发者指南.

类型: RouteSettings

必需: 否

AWS CloudFormation 兼容性: 此属性直接传递到 RouteSettings 属性 AWS::ApiGatewayV2::Stage 资源。

StageName

API阶段的名称。如果没有提供名称,SAM将使用 $default ApiGateway的阶段。

类型：字符串

必需: 否

默认:$默认

AWS CloudFormation 兼容性: 此属性直接传递到 StageName 属性 AWS::ApiGatewayV2::Stage 资源。

StageVariables

定义阶段的阶段变量的地图。变量名称可以包含字母数字和下划线字符，值必须匹配 [A-Za-z0-9-._~:/?#&=,]+。

类型：Json

必需: 否

AWS CloudFormation 兼容性: 此属性直接传递到 StageVariables 属性 AWS::ApiGatewayV2::Stage 资源。

Tags

指定要添加到此API网关环节的标记的映射(字符串到字符串)。键和值限于个字母数字字符。密钥的长度可以是1至127个Unicode字符,不能以aws前缀:。数值可以是1至255个Unicode字符。注意：标签需要 AWS SAM 修改您的 OpenAPI 定义。因此,只有当内联 OpenApi 定义为 DefinitionBody.

类型：Map

必需: 否

AWS CloudFormation 兼容性: 此属性是 AWS SAM 并且没有 AWS CloudFormation 等效。

其他备注: 因为标签需要 AWS SAM 修改您的 OpenAPI 定义,则只有在 DefinitionBody 属性已指定—如果 DefinitionUri 属性已提供。 AWS SAM 自动添加 httpapi:createdBy:SAM 标签。标记也将添加到 AWS::ApiGatewayV2::Stage 和 AWS::ApiGatewayV2::DomainName (如果 DomainName 已指定)。

返回值

Ref

当您将此资源的逻辑ID传递给内部参数时, Ref 功能, Ref 返回基础的APIID AWS::ApiGatewayV2::Api 资源,如a1bcdef2gh。

有关使用的更多信息 Ref 函数,请参阅 Ref 在 AWS CloudFormation 用户指南.

示例

简HttpApi

设置 HttpApi 端点由Lambda函数支持。这使用SAM创建的默认HTTPAPI。

YAML


AWSTemplateFormatVersion: '2010-09-09'
Description: AWS SAM template with a simple API definition
Resources:
  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: HttpApi
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
      Runtime: python3.7
Transform: AWS::Serverless-2016-10-31

HttpApi,带认证

如何在API端点上设置授权的示例。

YAML


Properties:
  FailOnWarnings: True
  Auth:
    DefaultAuthorizer: OAuth2
    Authorizers:
      OAuth2:
        AuthorizationScopes:
          - scope4
        JwtConfiguration:
          issuer: "https://www.example.com/v1/connect/oauth2"
          audience:
            - MyApi
        IdentitySource: "$request.querystring.param"
      OpenIdAuth:
        AuthorizationScopes:
          - scope1
          - scope2
        OpenIdConnectUrl: "https://www.example.com/v1/connect/oidc/.well-known/openid-configuration"
        JwtConfiguration:
          issuer: "https://www.example.com/v1/connect/oidc"
          audience:
            - MyApi
        IdentitySource: "$request.querystring.param"

HttpApi带 OpenApi 文档

显示如何添加 OpenApi 到文档。

请注意,SAM将填写缺少的任何lambda集成, HttpApi 引用此API的事件。SAM还将添加任何缺少的路径 HttpApi 事件参考。

YAML


Properties:
  FailOnWarnings: True
  DefinitionBody:
    info:
      version: '1.0'
      title:
        Ref: AWS::StackName
    paths:
      "/":
        get:
          security:
          - OpenIdAuth:
            - scope1
            - scope2
          responses: {}
    openapi: 3.0.1
    securitySchemes:
      OpenIdAuth:
        type: openIdConnect
        x-amazon-apigateway-authorizer:
          identitySource: "$request.querystring.param"
          type: jwt
          jwtConfiguration:
            audience:
            - MyApi
            issuer: https://www.example.com/v1/connect/oidc
          openIdConnectUrl: https://www.example.com/v1/connect/oidc/.well-known/openid-configuration

带配置设置的HttpApi

显示如何将API和阶段配置添加到模板。

YAML


AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Parameters:
  StageName:
    Type: String
    Default: Prod
    
Resources:
  HttpApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      InlineCode: |
          def handler(event, context):
              import json
              return {
                  "statusCode": 200,
                  "body": json.dumps(event),
              }
      Handler: index.handler
      Runtime: python3.7
      Events:
        ExplicitApi: # warning: creates a public endpoint
          Type: HttpApi
          Properties:
            ApiId: !Ref HttpApi
            Method: GET
            Path: /path
            TimeoutInMillis: 15000
            PayloadFormatVersion: "2.0"
            RouteSettings:
              ThrottlingBurstLimit: 600

  HttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: !Ref StageName
      Tags:
        Tag: Value
      AccessLogSettings:
        DestinationArn: !GetAtt AccessLogs.Arn
        Format: $context.requestId
      DefaultRouteSettings:
        ThrottlingBurstLimit: 200
      RouteSettings:
        "GET /path":
          ThrottlingBurstLimit: 500 # overridden in HttpApi Event
      StageVariables:
        StageVar: Value
      FailOnWarnings: True

  AccessLogs:
    Type: AWS::Logs::LogGroup

Outputs:
  HttpApiUrl:
    Description: URL of your API endpoint
    Value:
      Fn::Sub: 'https://${HttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/${StageName}/'
  HttpApiId:
    Description: Api id of HttpApi
    Value:
      Ref: HttpApi

Javascript 在您的浏览器中被禁用或不可用。

要使用 AWS 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

FunctionCode

HttpApiAuth