语法属性返回值示例

AWS::Serverless::HttpApi

创建 Amazon API Gateway HTTP API，这让您可以创建比 REST API 具有更低延迟和更低成本的 RESTful API。有关更多信息，请参阅《API Gateway 开发人员指南》中的使用 HTTP API。

我们建议您使用 CloudFormation 钩子或 IAM 策略来验证 API Gateway 资源是否附加了授权方以控制对它们的访问。

有关使用 CloudFormation 钩子的更多信息，请参阅《CloudFormation CLI 用户指南》中的注册钩子和 apigw-enforce-authorizer GitHub 存储库。

有关使用 IAM 策略的更多信息，请参阅《API Gateway 开发人员指南》中的要求 API 路由具有授权。

注意

部署到 AWS CloudFormation 时，AWS SAM 会将您的 AWS SAM 资源转换为 CloudFormation 资源。有关更多信息，请参阅为 AWS SAM 生成的 CloudFormation 资源。

语法

要在您的 AWS Serverless Application Model (AWS SAM) 模板中声明此实体，请使用以下语法。

YAML


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

属性

AccessLogSettings

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

类型：AccessLogSettings

必需：否

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

Auth

配置授权，以控制对 API Gateway HTTP API 的访问。

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

类型：HttpApiAuth

必需：否

CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 CloudFormation 等效属性。

CorsConfiguration

为所有 API Gateway HTTP API 管理跨源资源共享 (CORS)。以字符串形式指定要允许的域，或者指定一个 HttpApiCorsConfiguration 对象。请注意，CORS 需要 AWS SAM 修改您的 OpenAPI 定义，因此 CORS 只有在指定 DefinitionBody 属性时才起作用。

有关更多信息，请参阅《API Gateway 开发人员指南》中的为 HTTP API 配置 CORS。

注意

如果在 OpenAPI 定义中和属性级别都设置了 CorsConfiguration，则 AWS SAM 会将两个配置源合并，且属性优先。如果将此属性设置为 true，则允许所有来源。

类型：字符串 | HttpApiCorsConfiguration

必需：否

CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 CloudFormation 等效属性。

DefaultRouteSettings

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

类型：RouteSettings

必需：否

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

DefinitionBody

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

类型：JSON

必需：否

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

DefinitionUri

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

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

您通过 DefinitionUri 引用的外部 OpenApi 定义文件不支持内置函数。要将 OpenApi 定义导入到模板中，请使用带有 Include 转换的 DefinitionBody 属性。

类型：字符串 | HttpApiDefinition

必需：否

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

Description

HTTP API 资源的描述。

当您指定 Description 时，AWS SAM 将通过设置 description 字段来修改 HTTP API 资源的 OpenAPI 定义。以下情况将导致错误：

DefinitionBody 属性是使用 Open API 定义中设置的 description 字段指定的 – 这会导致 AWS SAM 无法解析的 description 字段冲突。
DefinitionUri 属性已指定 – AWS SAM 不会修改从 Amazon S3 检索到的 Open API 定义。

类型：字符串

必需：否

CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 CloudFormation 等效属性。

DisableExecuteApiEndpoint

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

要使用此属性，您必须指定 DefinitionBody 属性而不是 DefinitionUri 属性，或在 OpenAPI 定义中使用 disableExecuteApiEndpoint 定义 x-amazon-apigateway-endpoint-configuration。

类型：布尔值

必需：否

CloudFormation 兼容性：此属性类似于 AWS::ApiGatewayV2::Api 资源的 DisableExecuteApiEndpoint 属性。它直接传递给 x-amazon-apigateway-endpoint-configuration 扩展的 disableExecuteApiEndpoint 属性，然后添加到 AWS::ApiGatewayV2::Api 资源的 Body 属性中。

Domain

为此 API Gateway HTTP API 配置自定义域。

类型：HttpApiDomainConfiguration

必需：否

CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 CloudFormation 等效属性。

FailOnWarnings

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

类型：布尔值

必需：否

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

Name

HTTP API 资源的名称。

当您指定 Name 时，AWS SAM 将通过设置 title 字段来修改 HTTP API 资源的 OpenAPI 定义。以下情况将导致错误：

DefinitionBody 属性是使用 Open API 定义中设置的 title 字段指定的 – 这会导致 AWS SAM 无法解析的 title 字段冲突。
DefinitionUri 属性已指定 – AWS SAM 不会修改从 Amazon S3 检索到的 Open API 定义。

类型：字符串

必需：否

CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 CloudFormation 等效属性。

PropagateTags

指明是否将 Tags 属性中的标签传递给 AWS::Serverless::HttpApi 生成的资源。指定 True 以在生成的资源中传播标签。

类型：布尔值

必需：否

默认值：False

CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 CloudFormation 等效属性。

RouteSettings

此 HTTP API 的每个路由的路由设置。要了解更多信息，请参阅《API Gateway 开发人员指南》中的使用 HTTP API 的路由。

类型：RouteSettings

必需：否

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

StageName

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

类型：字符串

必需：否

默认值：$default

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

StageVariables

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

类型：Json

必需：否

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

Tags

指定要添加到此 API Gateway 阶段的标签的映射（字符串到字符串）。密钥的长度可以在 1 到 128 个 Unicode 字符之间，并且不能包含前缀 aws:。您可以使用以下任一字符：Unicode 字母、数字、空格、_、.、/、=、+ 和 - 的组合。值的长度可以在 1 到 256 个 Unicode 字符之间。

类型：映射

必需：否

CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 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 函数的更多信息，请参阅《AWS CloudFormation 用户指南》中的 Ref。

示例

简单 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"

HttpApi 和 OpenAPI 定义

以下示例说明如何将 OpenAPI 定义添加到模板。

请注意，对于引用此 HTTP API 的 HttpApi 事件，AWS SAM 会填写所有缺失的 Lambda 集成。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 在您的浏览器中被禁用或不可用。

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

文档惯例

运行时

HttpApiAuth