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

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

AWS::Serverless::HttpApi

创建API网关HTTPAPI,使您能够创建 RESTful APIs 相比REST具有更低的延迟和更低的成本 APIs。有关HTTP的更多信息 APIs 参见 HTTPAPI(HTTPAPI) 在 API 网关 开发人员指南.

语法

若要在您的 AWS 无服务器应用程序模型 (AWS SAM)模板,请使用以下语法。

属性

AccessLogSettings

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

类型: AccessLogSettings

必需: 否

AWS CloudFormation 兼容性: 此属性直接传递到 AccessLogSettings 属性 AWS::ApiGatewayV2::Stage 资源。

Auth

配置授权以控制对您的的访问 API 网关 API。

有关配置访问的更多信息,请参阅 JWT授权者 在 API 网关 开发者指南.

类型: HttpApiAuth

必需: 否

AWS CloudFormation 兼容性: 此属性是 AWS SAM 并且没有 AWS CloudFormation 等效。

CorsConfiguration

管理所有HTTP的跨源资源共享(CORS) APIs。指定域以允许作为字符串或指定具有其他Cors配置的字典。注意:CORS需要 AWS SAM 修改您的 OpenAPI 定义。因此,它只能在线运行 OpenApi 使用 DefinitionBody.

有关CORS的更多信息,请参阅 为HTTPAPI配置CORS 的AmazonAPIGatewayDeveloperGuide中。

注意:如果 CorsConfiguration 都设定于 OpenAPI 在酒店层面, AWS SAM 将其与属性合并,属性优先。

注意:如果此属性设置为 True 则允许所有起运地。

类型:字符串| HttpApiCorsConfiguration

必需: 否

AWS CloudFormation 兼容性: 此属性是 AWS SAM 并且没有 AWS CloudFormation 等效。

DefaultRouteSettings

此HTTPAPI的默认路由设置。这些设置适用于所有路由,除非被 RouteSettings 属性。

类型: RouteSettings

必需: 否

AWS CloudFormation 兼容性: 此属性直接传递到 RouteSettings 属性 AWS::ApiGatewayV2::Stage 资源。

DefinitionBody

OpenAPI 描述您的API的规范。如果两者都不是 DefinitionUriDefinitionBody 指定,SAM将生成 DefinitionBody 根据您的模板配置。

类型:字符串

必需: 否

AWS CloudFormation 兼容性: 该属性类似于 Body 属性 AWS::ApiGatewayV2::Api 资源。如果提供了某些属性,则可以在 DefinitionBody 之后再转到 CloudFormation。属性包括 Auth 以及 EventSource 类型 HttpApi 对应 AWS::Serverless::Function.

DefinitionUri

AWSS3Uri、本地文件路径或 OpenAPI 定义API的文档。此属性引用的AWSS3对象必须是有效的 OpenAPI 文件。如果两者都不是 DefinitionUriDefinitionBody 指定,SAM将生成 DefinitionBody 根据您的模板配置。

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

外部不支持内部函数 OpenApi 文件引用者 DefinitionUri。使用 DefinitionBody 属性,带有 包括转换 以导入 OpenApi 定义到模板中。

类型:字符串| HttpApiDefinition

必需: 否

AWS CloudFormation 兼容性: 该属性类似于 BodyS3Location 属性 AWS::ApiGatewayV2::Api 资源。嵌套 Amazon S3 属性的名称不同。

Domain

配置此的自定义域 API 网关 API。

类型: HttpApiDomainConfiguration

必需: 否

AWS CloudFormation 兼容性: 此属性是 AWS SAM 并且没有 AWS CloudFormation 等效。

FailOnWarnings

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

类型:布尔值

必需: 否

AWS CloudFormation 兼容性: 此属性直接传递到 FailOnWarnings 属性 AWS::ApiGatewayV2::Api 资源。

RouteSettings

此HTTPAPI的按路由路由设置。有关路由设置的更多信息,请参阅 AWS::ApiGatewayV2::阶段 RouteSettings 在 API 网关 开发者指南.

类型: RouteSettings

必需: 否

AWS CloudFormation 兼容性: 此属性直接传递到 RouteSettings 属性 AWS::ApiGatewayV2::Stage 资源。

StageName

API阶段的名称。如果没有提供名称,SAM将使用 $default ApiGateway的阶段。

类型:字符串

必需: 否

默认:$默认

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字符。注意:标签需要 AWS SAM 修改您的 OpenAPI 定义。因此,只有当内联 OpenApi 定义为 DefinitionBody.

类型:Map

必需: 否

AWS CloudFormation 兼容性: 此属性是 AWS SAM 并且没有 AWS CloudFormation 等效。

其他备注: 因为标签需要 AWS SAM 修改您的 OpenAPI 定义,则只有在 DefinitionBody 属性已指定—如果 DefinitionUri 属性已提供。 AWS SAM 自动添加 httpapi:createdBy:SAM 标签。标记也将添加到 AWS::ApiGatewayV2::StageAWS::ApiGatewayV2::DomainName (如果 DomainName 已指定)。

返回值

Ref

当您将此资源的逻辑ID传递给内部参数时, Ref 功能, Ref 返回基础的APIID AWS::ApiGatewayV2::Api 资源,如a1bcdef2gh。

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

示例

简HttpApi

设置 HttpApi 端点由Lambda函数支持。这使用SAM创建的默认HTTPAPI。

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,带认证

如何在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 到文档。

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

显示如何将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