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

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

AWS::Serverless::Api

创建可通过 HTTPS 终端节点调用的 Amazon API Gateway 资源和方法的集合。

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的AWS::Serverless::Api不需要将资源明确添加到Amazon无服务器应用程序定义模板。这种类型的资源是根据上定义的 Api 事件的联合隐式创建的AWS::Serverless::Function模板中定义的未引用AWS::Serverless::Api资源。

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的AWS::Serverless::Api应使用资源来使用 OpenAPI 定义和记录 API,该 API 提供了配置底层 Amazon API Gateway 资源的更多功能。

Syntax

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

Properties

AccessLogSetting

为阶段配置访问日志设置。

类型AccessLogSetting

必需:否

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

Auth

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

有关配置访问权限的更多信息Amazon SAM请参阅控制对 API Gateway API 的访问.

类型ApiAuth

必需:否

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

BinaryMediaTypes

API 可以返回的 MIME 类型列表。使用它可以启用对 API 的二进制支持。在 mime 类型中使用 ~1 而不是/。

类型:List

必需:否

Amazon CloudFormation兼容性:此属性类似于BinaryMediaTypes一个的财产AWS::ApiGateway::RestApi资源。BinaryMediaTypes 的列表已添加到两个Amazon CloudFormation资源和 OpenAPI 文档。

CacheClusterEnabled

指示是否为阶段启用缓存群集。

类型:Boolean

必需:否

Amazon CloudFormation兼容性:此属性将直接传递给CacheClusterEnabled一个的财产AWS::ApiGateway::Stage资源。

CacheClusterSize

阶段的缓存群集大小。

类型:String

必需:否

Amazon CloudFormation兼容性:此属性将直接传递给CacheClusterSize一个的财产AWS::ApiGateway::Stage资源。

CanarySetting

将 Canary 设置配置为常规部署阶段。

类型CanarySetting

必需:否

Amazon CloudFormation兼容性:此属性将直接传递给CanarySetting一个的财产AWS::ApiGateway::Stage资源。

Cors

管理所有 API Gateway API 的跨源资源共享 (CORS)。将允许的域指定为字符串,或者指定带有其他 Cos 配置的字典。注意:CORS 需要Amazon SAM以修改 OpenAPI 定义。因此,只有在使用 DineitionBody 定义了内联 OpenAPI 时,它才有效。

有关 CORS 的更多信息,请参阅。为 API Gateway API 资源启用 CORS中的API Gateway 开发人员指南.

类型:字符串 |CorsConfiguration

必需:否

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

DefinitionBody

描述你的 API 的 OpenAPI 规范。如果都不是DefinitionUrinorDefinitionBody已指定,SAM 将生成DefinitionBody根据你的模板配置。

类型:String

必需:否

Amazon CloudFormation兼容性:此属性类似于Body一个的财产AWS::ApiGateway::RestApi资源。如果提供了某些属性,则可以在传递给 CloudFormation 之前将内容插入或修改到 DefintionBody 中。属性包括AuthBinaryMediaTypesCorsGatewayResponsesModels,还有EventSource的类型为相应的 ApiAWS::Serverless::Function.

DefinitionUri

Amazon S3 Uri、本地文件路径或定义 OpenAPI 文档的位置对象。此属性引用的 Amazon S3 对象必须是有效的 OpenAPI 文件。如果都不是DefinitionUrinorDefinitionBody已指定,SAM 将生成DefinitionBody根据你的模板配置。

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

引用的外部 OpenAPI 文件不支持内在函数DefinitionUri. 请改用DefinitionBody房地产与包括转换将 OpenAPI 定义导入到模板中。

类型:字符串 |API 定义

必需:否

Amazon CloudFormation兼容性:此属性类似于BodyS3Location一个的财产AWS::ApiGateway::RestApi资源。嵌套的 Amazon S3 属性的命名方式不同。

Description

Api 资源的描述。

类型:String

必需:否

Amazon CloudFormation兼容性:此属性将直接传递给Description一个的财产AWS::ApiGateway::RestApi资源。

Domain

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

类型DomainConfiguration

必需:否

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

EndpointConfiguration

REST API 的终端节点类型。

类型EndpointConfiguration

必需:否

Amazon CloudFormation兼容性:此属性类似于EndpointConfiguration一个的财产AWS::ApiGateway::RestApi资源。嵌套配置属性的命名方式不同。

GatewayResponses

为 API 配置网关响应。网关响应是 API Gateway 直接或通过使用 Lambda 授权方返回的响应。有关更多信息,请参阅用于网关响应的 API 网关 OpenAPI 扩展.

类型:Map

必需:否

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

MethodSettings

配置 API 阶段的所有设置,包括日志记录、指标、cachettl 和限制。

类型MethodSettings

必需:否

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

MinimumCompressionSize

允许根据客户端的 Accept-Encode 标头压缩响应正文。当响应正文大小大于或等于您配置的阈值时,将触发压缩。最大正文大小阈值为 10 MB(10,485,760 字节)。-支持以下压缩类型:gzip、缩减和身份。

类型:整数

必需:否

Amazon CloudFormation兼容性:此属性将直接传递给MinimumCompressionSize的财产AWS::ApiGateway::RestApi资源。

Mode

此属性仅在您使用 OpenAPI 定义 REST API 时才适用。Mode 确定 API Gateway 如何处理资源更新。有关更多信息,请参阅 。Mode (模式)的财产AWS::ApiGateway::RestApi资源类型。

有效值overwritemerge

类型:String

必需:否

Amazon CloudFormation兼容性:此属性将直接传递给Mode的财产AWS::ApiGateway::RestApi资源。

Models

API 方法要使用的模式。这些模式可以使用 JSON 或 YAML 进行描述。有关示例模型,请参阅该页面底部的示例部分。

类型:Map

必需:否

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

Name

API Gateway RestApi 资源的名称

类型:String

必需:否

Amazon CloudFormation兼容性:此属性将直接传递给Name的财产AWS::ApiGateway::RestApi资源。

OpenApiVersion

要使用的 OpenAPI 版本。这可以是2.0对于 Swagger 规范或 OpenAPI 3.0 版本之一,例如3.0.1. 有关 OpenAPI 的更多信息,请参阅OpenAPI 规格.

注意:将此属性设置为任何有效值也将删除舞台StageSAM 创造的。

类型:String

必需:否

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

StageName

阶段的名称,API Gateway 将其用作调用统一资源标识符 (URI) 中的第一个路径部分。

要引用舞台资源,请使用<api-logical-id>.Stage. 有关引用以下情况下生成的资源的更多信息。AWS::Serverless::Api已指定资源,请参阅Amazon CloudFormation指定 aws:: Serverless። Api 时生成的资源. 有关生成的一般信息Amazon CloudFormation资源,请参阅生成Amazon CloudFormationresources.

类型:String

必需:是

Amazon CloudFormation兼容性:此属性类似于StageName的财产AWS::ApiGateway::Stage资源。它在 SAM 中是必需的,但在 API Gateway 中不是必需的

附加说明:隐式 API 的阶段名称为 “Prod”。

Tags

一个映射(字符串到字符串),指定要添加到该 API Gateway 阶段的标签。有关标签的有效密钥和值的详细信息,请参阅资源标签中的 Amazon CloudFormation 用户指南.

类型:Map

必需:否

Amazon CloudFormation兼容性:此属性类似于Tags的财产AWS::ApiGateway::Stage资源。SAM 中的 Tags 属性由键:Value 对组成;在 CloudFormation 中,它由标签对象的列表组成。

TracingEnabled

指示是否为阶段启用使用 X-Ray 进行的主动跟踪。有关 X-Ray 的更多信息,请参阅使用 X-Ray 跟踪用户对 REST API 的请求中的API Gateway 开发人员指南.

类型:Boolean

必需:否

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

Variables

一个映射(字符串到字符串),它定义阶段变量,其中变量名为键,变量值为值。变量名称只能包含字母数字字符。值必须匹配以下正则表达式:[A-Za-z0-9._~:/?#&=,-]+

类型:Map

必需:否

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

返回值

Ref

当该资源的逻辑 ID 提供给Ref内在函数,它返回底层 API Gateway API 的 ID。

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

Fn::GetAtt

Fn::GetAtt 返回一个此类型指定属性的值。以下为可用属性和示例返回值。

有关使用的更多信息Fn::GetAtt,请参阅Fn::GetAtt中的 Amazon CloudFormation 用户指南.

RootResourceId

RestApi 资源的根资源 ID,例如 a0bc123d4e

Examples

SimpleApiExample

Hello WorldAmazon SAM包含带 API 终端节点的 Lambda 函数的模板文件。这是完整的Amazon SAM工作无服务器应用程序的模板文件。

YAML

AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: Amazon SAM template with a simple API definition Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: prod ApiFunction: # Adds a GET api endpoint at "/" to the ApiGatewayApi via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.7 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200}

ApiCorsExample

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的Amazon SAM模板片段,其中包含在外部 Swagger 文件中定义的 API 以及 Lambda 集成和 CORS 配置。这只是一个版本的一部分Amazon SAM显示模板文件AWS::Serverless::Api定义。

YAML

Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod # Allows www.example.com to call these APIs # SAM will automatically add AllowMethods with a list of methods for this API Cors: "'www.example.com'" DefinitionBody: # Pull in an OpenApi definition from S3 'Fn::Transform': Name: 'AWS::Include' # Replace "bucket" with your bucket name Parameters: Location: s3://bucket/swagger.yaml

ApiCognitoAuthExample

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的Amazon SAM带有使用 Amazon Cognito 授权针对 API 的请求的 API 的模板片段。这只是一个版本的一部分Amazon SAM显示模板文件AWS::Serverless::Api定义。

YAML

Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Cors: "'*'" Auth: DefaultAuthorizer: MyCognitoAuthorizer Authorizers: MyCognitoAuthorizer: UserPoolArn: Fn::GetAtt: [MyCognitoUserPool, Arn]

ApiModelsExample

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的Amazon SAM带有包含模型架构的 API 的模板片段。这只是一个版本的一部分Amazon SAM模板文件,显示AWS::Serverless::Api用两个模型模式进行定义。

YAML

Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: Prod Models: User: type: object required: - username - employee_id properties: username: type: string employee_id: type: integer department: type: string Item: type: object properties: count: type: integer category: type: string price: type: integer