本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
AWS::Serverless::HttpApi
创建 Amazon API Gateway HTTP API,它使您能够创建比 REST RESTful 具有更低延迟和更低成本的 APIs APIs。 有关更多信息,请参阅 APIs 中的使用 HTTP 。API 网关 开发人员指南
语法
在您的 中声明此实体 AWS 无服务器应用程序模型 (AWS SAM) 模板时,请使用以下语法。
YAML
Type: AWS::Serverless::HttpApi Properties: AccessLogSettings:
AccessLogSettings
Auth:HttpApiAuth
CorsConfiguration:String | HttpApiCorsConfiguration
DefaultRouteSettings:RouteSettings
DefinitionBody:String
DefinitionUri:String | HttpApiDefinition
Description:String
DisableExecuteApiEndpoint:Boolean
Domain:HttpApiDomainConfiguration
FailOnWarnings:Boolean
RouteSettings:RouteSettings
StageName:String
StageVariables:Json
Tags:Map
属性
-
AccessLogSettings
-
阶段中访问日志记录的设置。
必需: 否
AWS CloudFormation 兼容性:此属性直接传递给
AccessLogSettings
资源的AWS::ApiGatewayV2::Stage
属性。 -
Auth
-
配置授权以控制对 API 网关 HTTP API 的访问。
有关更多信息,请参阅 中的APIs使用 JWT 授权方控制对 HTTP 的访问。API 网关 开发人员指南
类型: HttpApiAuth
必需: 否
兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS CloudFormation。
-
CorsConfiguration
-
管理您的所有 API 网关 HTTP APIs 的跨源资源共享 (CORS)。 指定要允许使用作为字符串的域,或指定
HttpApiCorsConfiguration
对象。请注意,CORS 要求 AWS SAM 修改您的 OpenAPI 定义,因此 CORS 仅在指定了DefinitionBody
属性时才起作用。有关更多信息,请参阅 https://docs.amazonaws.cn/apigateway/latest/developerguide/http-api-cors.html 中的为 HTTP API 配置 CORSAPI 网关 开发人员指南。
注意:如果在
CorsConfiguration
定义中和属性级别都设置了 OpenAPI,则 AWS SAM 会将两个配置源合并并优先使用属性。注意:如果该属性设置为
true
,则允许所有源。类型: String | HttpApiCorsConfiguration
必需: 否
兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS CloudFormation。
-
DefaultRouteSettings
-
此 HTTP API 的默认路由设置。这些设置适用于所有路由,除非被特定路由的
RouteSettings
属性覆盖。类型: RouteSettings
必需: 否
兼容性AWS CloudFormation:此属性直接传递给
RouteSettings
资源的AWS::ApiGatewayV2::Stage
属性。 -
DefinitionBody
-
描述 HTTP API 的 OpenAPI 定义。如果未指定
DefinitionUri
或DefinitionBody
,AWS SAM 将根据您的模板配置为您生成DefinitionBody
。类型:字符串
必需: 否
兼容性AWS CloudFormation:此属性类似于
Body
资源的AWS::ApiGatewayV2::Api
属性。如果提供了某些属性,则 AWS SAM 可能会在将内容传递到DefinitionBody
之前将内容插入到 AWS CloudFormation 中或修改它。属性包括相应Auth
资源的EventSource
和 HttpApi 类型的AWS::Serverless::Function
。 -
DefinitionUri
-
定义 HTTP API 的 Amazon Simple Storage Service 定义的 Amazon S3 (OpenAPI) URI、本地文件路径或位置对象。该属性引用的 Amazon S3 对象必须是有效的 OpenAPI 定义文件。如果未指定
DefinitionUri
或指定DefinitionBody
,AWS SAM 将根据您的模板配置为您生成DefinitionBody
。如果您提供了本地文件路径,则模板必须执行包含
sam deploy
或sam package
命令的工作流程,才能正确转换定义。在通过 OpenApi 引用的外部
DefinitionUri
定义文件中,不支持内部函数。 要将 OpenApi 定义导入到模板中,请将DefinitionBody
属性与 Include transform (包括转换) 结合使用。类型: String | HttpApiDefinition
必需: 否
兼容性AWS CloudFormation:此属性类似于
BodyS3Location
资源的AWS::ApiGatewayV2::Api
属性。嵌套 Amazon S3 属性的命名方式不同。 -
Description
-
HttpApi 资源的描述。
类型:字符串
必需: 否
兼容性AWS CloudFormation:此属性直接传递给
Description
资源的AWS::ApiGatewayV2::Api
属性。 -
DisableExecuteApiEndpoint
-
指定客户端是否可以使用默认的
execute-api
终端节点https://{api_id}.execute-api.{region}.amazonaws.com
调用您的 HTTP API。 默认情况下,客户端可以使用默认终端节点调用您的 API。要要求客户端仅使用自定义域名调用 API,请禁用默认终端节点。类型:布尔值
必需: 否
兼容性AWS CloudFormation:此属性直接传递给
DisableExecuteApiEndpoint
资源的AWS::ApiGatewayV2::Api
属性。 -
Domain
-
为此 API 网关 HTTP API 配置自定义域。
类型: HttpApiDomainConfiguration
必需: 否
兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS CloudFormation。
-
FailOnWarnings
-
指定在遇到警告时是回滚 HTTP API 创建 (
true
) 还是不回滚 (false
)。默认值为false
。类型:布尔值
必需: 否
兼容性AWS CloudFormation:此属性直接传递给
FailOnWarnings
资源的AWS::ApiGatewayV2::Api
属性。 -
RouteSettings
-
此 HTTP API 的每路由的路由设置。有关更多信息,请参阅 APIs 中的使用 HTTP 的路由API 网关 开发人员指南。
类型: RouteSettings
必需: 否
兼容性AWS CloudFormation:此属性直接传递给
RouteSettings
资源的AWS::ApiGatewayV2::Stage
属性。 -
StageName
-
API 阶段的名称。如果未指定名称,AWS SAM 将使用
$default
中的 API 网关 阶段。类型:字符串
必需: 否
默认值:$default
兼容性AWS CloudFormation:此属性直接传递给
StageName
资源的AWS::ApiGatewayV2::Stage
属性。 -
StageVariables
-
一个定义阶段变量的映射。变量名称可以包含字母数字和下划线字符。值必须匹配 [A-Za-z0-9-._~:/?#&;=,]+。
类型:Json
必需: 否
兼容性AWS CloudFormation:此属性直接传递给
StageVariables
资源的AWS::ApiGatewayV2::Stage
属性。 -
Tags
-
指定要添加到此 API 网关 阶段的标签的映射(字符串到字符串)。键和值仅限于字母数字字符。键的长度可以在 1 到 127 个 Unicode 字符之间,并且不能包含前缀
aws:
。 值的长度可以是 1 到 255 个 Unicode 字符。类型:Map
必需: 否
兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS 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
函数的更多信息,请参阅 中的 Ref
AWS CloudFormation 用户指南。
示例
简单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" 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"
HttpApi 与 OpenAPI 定义
以下示例演示如何将 OpenAPI 定义添加到模板中。
请注意,AWS SAM 会填充引用此 HTTP API 的 Lambda 事件的任何缺失的 HttpApi 集成。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