本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
AWS::Serverless::HttpApi
创建 Amazon API Gateway HTTP API,这让您可以创建比 REST API 具有更低延迟和更低成本的 RESTful API。有关更多信息,请参阅《API Gateway 开发人员指南》中的使用 HTTP API。
我们建议您使用 Amazon CloudFormation 挂钩或 IAM 策略来验证 API Gateway 资源是否附加了授权者来控制对它们的访问。
有关使用 Amazon CloudFormation 挂钩的更多信息,请参阅 Amazon CloudFormation CLI 用户指南和apigw-enforce-authorizer
有关使用 IAM 策略的更多信息,请参阅《API Gateway 开发人员指南》中的要求 API 路由具有授权。
注意
部署到时 Amazon CloudFormation, Amazon SAM 会将您的 Amazon SAM 资源转换为 Amazon CloudFormation 资源。有关更多信息,请参阅 生成的 Amazon CloudFormation 资源用于 Amazon SAM。
语法
要在 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
Name:String
PropagateTags:Boolean
RouteSettings:RouteSettings
StageName:String
StageVariables:Json
Tags:Map
属性
-
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 管理跨源资源共享 (CORS)。以字符串形式指定要允许的域,或者指定一个
HttpApiCorsConfiguration
对象。请注意,CORS Amazon SAM 需要修改你的 OpenAPI 定义,因此 CORS 只有在指定DefinitionBody
了该属性时才起作用。有关更多信息,请参阅《API Gateway 开发人员指南》中的为 HTTP API 配置 CORS。
注意
如果
CorsConfiguration
在 OpenAPI 定义和属性级别都进行了设置,则会将两个配置源 Amazon SAM 合并,且属性优先。如果将此属性设置为true
,则允许所有来源。类型:字符串 | HttpApiCorsConfiguration
必需:否
Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。
-
DefaultRouteSettings
-
此 HTTP API 的默认路由设置。这些设置适用于所有路由,除非被某些路由的
RouteSettings
属性覆盖。必需:否
Amazon CloudFormation 兼容性:此属性直接传递给
AWS::ApiGatewayV2::Stage
资源的RouteSettings
属性。 -
DefinitionBody
-
描述您的 HTTP API 的 OpenAPI 定义。如果您未指定 a
DefinitionUri
或 aDefinitionBody
,则会根据您的模板配置DefinitionBody
为您 Amazon SAM 生成。类型:JSON
必需:否
Amazon CloudFormation 兼容性:此属性类似于
AWS::ApiGatewayV2::Api
资源的Body
属性。如果提供了某些属性,则 Amazon SAM 可以在将内容传递给DefinitionBody
之前将其插入或修改 Amazon CloudFormation。属性包括相应EventSource
HttpApiAWS::Serverless::Function
资源的类型Auth
和类型。 -
DefinitionUri
-
定义 HTTP API 的 OpenAPI 定义的 Amazon Simple Storage Service (Amazon S3) URI、本地文件路径或位置对象。此属性引用的 Amazon S3 对象必须是有效的 OpenAPI 定义文件。如果您未指定
DefinitionUri
或DefinitionBody
已指定,则会根据您的模板配置DefinitionBody
为您 Amazon SAM 生成。如果您提供本地文件路径,则模板必须经过包含
sam deploy
或sam package
命令的工作流程,才能使定义正确转换。您引用的外部 OpenApi 定义文件不支持内部函数。
DefinitionUri
要将 OpenApi 定义导入到模板中,请使用带有 Include 转换的DefinitionBody
属性。类型:字符串 | HttpApiDefinition
必需:否
Amazon CloudFormation 兼容性:此属性类似于
AWS::ApiGatewayV2::Api
资源的BodyS3Location
属性。嵌套的 Amazon S3 属性的命名有所不同。 -
Description
-
HTTP API 资源的描述。
当您指定时
Description
, Amazon SAM 将通过设置description
字段来修改 HTTP API 资源的OpenApi 定义。以下情况将导致错误:-
该
DefinitionBody
属性是使用 Open API 定义中设置的description
字段指定的,这会导致 Amazon SAM 无法解决的description
字段冲突。 -
该
DefinitionUri
属性已指定 — Amazon SAM 不会修改从 Amazon S3 检索到的开放 API 定义。
类型:字符串
必需:否
Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon 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
进行定义。类型:布尔值
必需:否
Amazon CloudFormation 兼容性:此属性类似于
AWS::ApiGatewayV2::Api
资源的DisableExecuteApiEndpoint
属性。它直接传递给x-amazon-apigateway-endpoint-configuration
扩展的disableExecuteApiEndpoint
属性,然后添加到AWS::ApiGatewayV2::Api
资源的Body
属性中。 -
Domain
-
为此 API Gateway HTTP API 配置自定义域。
必需:否
Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。
-
FailOnWarnings
-
指定在遇到警告时是回滚 (
true
) 还是不回滚 (false
) HTTP API 创建。默认值为false
。类型:布尔值
必需:否
Amazon CloudFormation 兼容性:此属性直接传递给
AWS::ApiGatewayV2::Api
资源的FailOnWarnings
属性。 Name
-
HTTP API 资源的名称。
当您指定时
Name
, Amazon SAM 将通过设置该字段来修改 HTTP API 资源的 OpenAPI 定义。title
以下情况将导致错误:-
该
DefinitionBody
属性是使用 Open API 定义中设置的title
字段指定的,这会导致 Amazon SAM 无法解决的title
字段冲突。 -
该
DefinitionUri
属性已指定 — Amazon SAM 不会修改从 Amazon S3 检索到的开放 API 定义。
类型:字符串
必需:否
Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。
-
-
指明是否将
Tags
属性中的标签传递给 AWS::Serverless::HttpApi 生成的资源。指定True
以在生成的资源中传播标签。类型:布尔值
必需:否
默认值:
False
Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。
-
RouteSettings
-
此 HTTP API 的每个路由的路由设置。要了解更多信息,请参阅《API Gateway 开发人员指南》中的使用 HTTP API 的路由。
必需:否
Amazon CloudFormation 兼容性:此属性直接传递给
AWS::ApiGatewayV2::Stage
资源的RouteSettings
属性。 -
StageName
-
API 阶段的名称。如果未指定名称,则 Amazon SAM 使用 API Gateway 中的
$default
舞台。类型:字符串
必需:否
默认值:$default
Amazon CloudFormation 兼容性:此属性直接传递给
AWS::ApiGatewayV2::Stage
资源的StageName
属性。 -
StageVariables
-
一个定义阶段变量的映射。变量名可以包含字母数字和下划线字符。这些值必须匹配 [A-Za-z0-9-._~:/?#&=,]+。
类型:Json
必需:否
Amazon CloudFormation 兼容性:此属性直接传递给
AWS::ApiGatewayV2::Stage
资源的StageVariables
属性。 -
指定要添加到此 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
会返回底层 AWS::ApiGatewayV2::Api
资源的 API ID,例如 a1bcdef2gh
。
有关使用 Ref
函数的更多信息,请参阅《Amazon CloudFormation 用户指南》中的 Ref
。
示例
简单 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 定义添加到模板。
请注意,对于引用此 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