语法属性返回值示例

AWS::Serverless::HttpApi

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

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

有关使用的更多信息Amazon CloudFormation挂钩，请参阅注册挂钩中的Amazon CloudFormationCLI 用户指南和apigw 执行授权者 GitHub 存储库。

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

语法

在您的中声明此实体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
  FailOnWarnings: Boolean
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

属性

AccessLogSettings

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

类型：AccessLogSettings

必需：否

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

Auth

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

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

类型：httpPiAuth

必需：否

Amazon CloudFormation兼容性：此属性对是唯一的Amazon SAM而且没有Amazon CloudFormation等效项

CorsConfiguration

管理所有 API Gateway HTTP API 的跨源资源共享 (CORS)。指定要允许的域作为字符串，或者指定HttpApiCorsConfiguration对象。请注意，CORS 需要Amazon SAM修改你的 OpenAPI 定义，所以 CORS 只有在DefinitionBody属性已指定。

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

注意：如果CorsConfiguration在 OpenAPI 定义和属性级别都设置了，然后Amazon SAM将两个配置源与优先属性合并。

注意：如果此属性设置为true，那么所有的起源都被允许。

类型：字符串 |httpPicors配置

必需：否

Amazon CloudFormation兼容性：此属性对是唯一的Amazon SAM而且没有Amazon CloudFormation等效项

DefaultRouteSettings

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

类型：RouteSettings

必需：否

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

DefinitionBody

描述你的 HTTP API API 的 OpenAPI 定义。如果不指定DefinitionUri或者DefinitionBody、Amazon SAM生成DefinitionBody根据你的模板配置。

类型：JSON

必需：否

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

DefinitionUri

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

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

外部不支持内部函数 OpenApi 你引用的定义文件DefinitionUri. 导入 OpenApi 定义到模板中，使用DefinitionBody属性与包括转换.

类型：字符串 |HTTPAPI 定义

必需：否

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

Description

对的描述 HttpApi 资源。

注意：此属性需要Amazon SAM修改 HttpApi 资源的 OpenAPI 定义，用于设置description字段中返回的子位置类型。以下两种情况导致出现错误：(1) 该DefinitionBody属性是用descriptionOpenAPI 定义中设置的字段（因为这是一个冲突Amazon SAM不会解决），或者 2）DefinitionUri属性被指定（因为Amazon SAM不会修改它从 Amazon S3 中检索的 OpenAPI 定义）。

类型：字符串

必需：否

Amazon CloudFormation兼容性：此属性对是唯一的Amazon SAM而且没有Amazon CloudFormation等效项

DisableExecuteApiEndpoint

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

类型：布尔值

必需：否

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

Domain

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

类型：httpPid域名配置

必需：否

Amazon CloudFormation兼容性：此属性对是唯一的Amazon SAM而且没有Amazon CloudFormation等效项

FailOnWarnings

指定是否回滚 HTTP API 创建 (true）或不（false) 遇到警告时。原定设置值为 false。

类型：布尔值

必需：否

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

RouteSettings

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

类型：RouteSettings

必需：否

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

StageName

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

类型：字符串

必需：否

默认值：$default

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

StageVariables

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

类型：Json

必需：否

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

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资源和AWS::ApiGatewayV2::DomainName资源（如果DomainName已指定）。

返回值

Ref

将此资源的逻辑 ID 传递给内部Ref函数，Ref返回底层证券的 API IDAWS::ApiGatewayV2::Api例如，资源，a1bcdef2gh.

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

示例

Simple httpAPI

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

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

带身份验证的 HTTPi

以下示例说明如何在 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"

带 OpenAPI 定义的 HTTPi

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

请注意Amazon SAM填写任何缺少的 Lambda 集成 HttpApi 引用此 HTTP API 的事件。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

带配置设置的 HTTPi

以下示例说明如何将 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