语法属性返回值示例

AWS::Serverless::HttpApi

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

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

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

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

注意

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

语法

要在Amazon Serverless Application Model (Amazon 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
  EnableFunctionDefaultPermissions: Boolean
  FailOnWarnings: Boolean
  Name: String
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

属性

AccessLogSettings

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

类型：AccessLogSettings

必需：否

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

Auth

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

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

类型：HttpApiAuth

必需：否

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

CorsConfiguration

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

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

注意

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

类型：字符串 | HttpApiCorsConfiguration

必需：否

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

DefaultRouteSettings

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

类型：RouteSettings

必需：否

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

DefinitionBody

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

类型：JSON

必需：否

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

DefinitionUri

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

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

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

类型：字符串 | HttpApiDefinition

必需：否

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

Description

HTTP API 资源的描述。

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

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

类型：字符串

必需：否

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

DisableExecuteApiEndpoint

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

类型：布尔值

必需：否

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

Domain

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

类型：HttpApiDomainConfiguration

必需：否

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

EnableFunctionDefaultPermissions

默认情况下，不授予 HTTP API 资源调用 Lambda 授权器的权限。将此属性指定true为在您的 HTTP API 资源和 Lambda 授权者之间自动创建权限。

类型：布尔值

必需：否

默认值：false

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

FailOnWarnings

指定遇到警告时回滚 HTTP API 创建 (true) 或不回滚 HTTP API 创建 (false) 的 HTTP API 创建过程 ()。默认值为 false。

类型：布尔值

必需：否

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

Name

HTTP API 资源的名称。

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

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

类型：字符串

必需：否

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

RouteSettings

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

类型：RouteSettings

必需：否

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

StageName

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

类型：字符串

必需：否

默认值：$默认

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

StageVariables

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

类型：Json

必需：否

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

Tags

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

类型：地图

必需：否

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

附加说明：该Tags属性Amazon SAM需要修改您的 OpenAPI 定义，因此只有在指定了DefinitionBody属性时才添加标签，如果指定了该DefinitionUri属性，则不会添加任何标签。 Amazon SAM自动添加httpapi:createdBy:SAM标签。标签还会添加到AWS::ApiGatewayV2::Stage资源和资源（如果DomainName已指定）。AWS::ApiGatewayV2::DomainName

返回值

Ref

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

有关使用该Ref函数的更多信息，请参阅Ref《Amazon CloudFormation用户指南》。

示例

简单 HttpApi

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

YAML


AWSTemplateFormatVersion: '2010-09-09'
Description: Amazon 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 定义（OpenAPI）定义添加到模板。

请注意，对于引用此 HTTP API HttpApi 的事件，请Amazon SAM填写所有缺失的 Lambda 集成。 Amazon 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。请参阅浏览器的帮助页面以了解相关说明。

FunctionUrlConfig

HttpApiAuth