AWS::Serverless::HttpApi

创建 Amazon API Gateway HTTP API，它使您能够创建比 REST RESTful 具有更低延迟和更低成本的 APIs APIs。有关更多信息，请参阅 APIs 中的使用 HTTP 。API 网关开发人员指南

语法

在您的中声明此实体 AWS 无服务器应用程序模型（AWS SAM）模板时，请使用以下语法。

YAML


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

属性

AccessLogSettings

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

类型: AccessLogSettings

必需: 否

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

Auth

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

有关更多信息，请参阅中的APIs使用 JWT 授权方控制对 HTTP 的访问。API 网关开发人员指南

类型: HttpApiAuth

必需: 否

兼容性AWS CloudFormation：此属性对于 AWS SAM 是唯一的，没有等效的 AWS CloudFormation。

CorsConfiguration

管理您的所有 API 网关 HTTP APIs 的跨源资源共享（CORS）。指定要允许使用作为字符串的域，或指定 HttpApiCorsConfiguration 对象。请注意，CORS 要求 AWS SAM 修改您的 OpenAPI 定义，因此 CORS 仅在指定了 DefinitionBody 属性时才起作用。

有关更多信息，请参阅 https://docs.amazonaws.cn/apigateway/latest/developerguide/http-api-cors.html 中的为 HTTP API 配置 CORSAPI 网关开发人员指南。

注意：如果在 CorsConfiguration 定义中和属性级别都设置了 OpenAPI，则 AWS SAM 会将两个配置源合并并优先使用属性。

注意：如果该属性设置为 true，则允许所有源。

类型： String | HttpApiCorsConfiguration

必需: 否

兼容性AWS CloudFormation：此属性对于 AWS SAM 是唯一的，没有等效的 AWS CloudFormation。

DefaultRouteSettings

此 HTTP API 的默认路由设置。这些设置适用于所有路由，除非被特定路由的 RouteSettings 属性覆盖。

类型: RouteSettings

必需: 否

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

DefinitionBody

描述 HTTP API 的 OpenAPI 定义。如果未指定 DefinitionUri 或 DefinitionBody，AWS SAM 将根据您的模板配置为您生成 DefinitionBody。

类型：字符串

必需: 否

兼容性AWS CloudFormation：此属性类似于 Body 资源的 AWS::ApiGatewayV2::Api 属性。如果提供了某些属性，则 AWS SAM 可能会在将内容传递到 DefinitionBody 之前将内容插入到 AWS CloudFormation 中或修改它。属性包括相应 Auth 资源的 EventSource 和 HttpApi 类型的 AWS::Serverless::Function。

DefinitionUri

定义 HTTP API 的 Amazon Simple Storage Service 定义的 Amazon S3 （OpenAPI） URI、本地文件路径或位置对象。该属性引用的 Amazon S3 对象必须是有效的 OpenAPI 定义文件。如果未指定 DefinitionUri 或指定 DefinitionBody，AWS SAM 将根据您的模板配置为您生成 DefinitionBody。

如果您提供了本地文件路径，则模板必须执行包含 sam deploy 或 sam package 命令的工作流程，才能正确转换定义。

在通过 OpenApi 引用的外部 DefinitionUri 定义文件中，不支持内部函数。要将 OpenApi 定义导入到模板中，请将 DefinitionBody 属性与 Include transform （包括转换）结合使用。

类型： String | HttpApiDefinition

必需: 否

兼容性AWS CloudFormation：此属性类似于 BodyS3Location 资源的 AWS::ApiGatewayV2::Api 属性。嵌套 Amazon S3 属性的命名方式不同。

Description

HttpApi 资源的描述。

类型：字符串

必需: 否

兼容性AWS CloudFormation：此属性直接传递给 Description 资源的 AWS::ApiGatewayV2::Api 属性。

DisableExecuteApiEndpoint

指定客户端是否可以使用默认的 execute-api 终端节点 https://{api_id}.execute-api.{region}.amazonaws.com 调用您的 HTTP API。默认情况下，客户端可以使用默认终端节点调用您的 API。要要求客户端仅使用自定义域名调用 API，请禁用默认终端节点。

类型：布尔值

必需: 否

兼容性AWS CloudFormation：此属性直接传递给 DisableExecuteApiEndpoint 资源的 AWS::ApiGatewayV2::Api 属性。

Domain

为此 API 网关 HTTP API 配置自定义域。

类型: HttpApiDomainConfiguration

必需: 否

兼容性AWS CloudFormation：此属性对于 AWS SAM 是唯一的，没有等效的 AWS CloudFormation。

FailOnWarnings

指定在遇到警告时是回滚 HTTP API 创建（true）还是不回滚（false）。默认值为 false。

类型：布尔值

必需: 否

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

RouteSettings

此 HTTP API 的每路由的路由设置。有关更多信息，请参阅 APIs 中的使用 HTTP 的路由API 网关开发人员指南。

类型: RouteSettings

必需: 否

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

StageName

API 阶段的名称。如果未指定名称，AWS SAM 将使用 $default 中的 API 网关阶段。

类型：字符串

必需: 否

默认值：$default

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

StageVariables

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

类型：Json

必需: 否

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

Tags

指定要添加到此 API 网关阶段的标签的映射（字符串到字符串）。键和值仅限于字母数字字符。键的长度可以在 1 到 127 个 Unicode 字符之间，并且不能包含前缀 aws:。值的长度可以是 1 到 255 个 Unicode 字符。

类型：Map

必需: 否

兼容性AWS CloudFormation：此属性对于 AWS SAM 是唯一的，没有等效的 AWS CloudFormation。

其他说明：属性要求 Tags 修改您的 AWS SAM 定义，因此，只有在指定了 OpenAPI 属性时才添加标签DefinitionBody未指定 — 属性时，才会添加任何标签。DefinitionUri 自动添加 AWS SAM 标签。httpapi:createdBy:SAM标签也会添加到 AWS::ApiGatewayV2::Stage 资源和 AWS::ApiGatewayV2::DomainName 资源（如果指定了 DomainName）。

返回值

Ref

在将此资源的逻辑 ID 传递给内部 Ref 函数时，Ref 返回底层 AWS::ApiGatewayV2::Api 资源的 API ID，例如 a1bcdef2gh。

有关使用 Ref 函数的更多信息，请参阅中的 RefAWS CloudFormation 用户指南。

示例

简单HttpApi

以下示例显示了设置由 Lambda 函数支持的 HTTP API 终端节点所需的最少数量。此示例使用 AWS SAM 创建的默认 HTTP API。

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

以下示例演示如何在 HTTP 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 定义添加到模板中。

请注意，AWS SAM 会填充引用此 HTTP API 的 Lambda 事件的任何缺失的 HttpApi 集成。AWS 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

以下示例演示如何将 HTTP 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