AWS::Serverless::HttpApi - Amazon Serverless Application Model
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

AWS::Serverless::HttpApi

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

Syntax

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

Properties

AccessLogSettings

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

类型AccessLogSettings

必需:否

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

Auth

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

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

类型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根据你的模板配置。

类型:String

必需:否

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 定义)。

类型:String

必需:否

Amazon CloudFormation兼容性:该属性是唯一的Amazon SAM没有Amazon CloudFormation等效函数

DisableExecuteApiEndpoint

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

类型:Boolean

必需:否

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

Domain

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

类型httpPid域名配置

必需:否

Amazon CloudFormation兼容性:该属性是唯一的Amazon SAM没有Amazon CloudFormation等效函数

FailOnWarnings

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

类型:Boolean

必需:否

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 的阶段。

类型:String

必需:否

默认值:$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 字符。

类型:Map

必需:否

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 用户指南.

Examples

简便 HTTPAPI

以下示例显示了设置由 Lambda 函数支持的 HTTP API 终端节点所需的最低限度。此示例使用的是默认 HTTP APIAmazon 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

Auth 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"

这是 OpenAPI 定义

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

请注意Amazon SAM填写引用此 HTTP API 的 HTTPAPI 事件的任何缺失的 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