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

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

AWS::Serverless::Api

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

无需将 AWS::Serverless::Api 资源显式添加到 AWS 无服务器应用程序定义模板中。此类型的资源是隐式从在不引用 AWS::Serverless::Function 资源的模板中定义的 AWS::Serverless::Api 资源上定义的 Api 事件联合创建的。

资源应该用于定义和记录使用 AWS::Serverless::Api 的 API,它提供了配置底层 Amazon API Gateway 资源的更强大的功能。OpenApi

语法

在您的 中声明此实体 AWS 无服务器应用程序模型 (AWS SAM) 模板时,请使用以下语法。

属性

AccessLogSetting

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

类型: AccessLogSetting

必需: 否

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

Auth

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

有关使用 AWS SAM 配置访问权限的更多信息,请参阅控制对 API 网关 APIs 的访问

类型: ApiAuth

必需: 否

兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS CloudFormation。

BinaryMediaTypes

您的 API 可以返回的 MIME 类型的列表。使用此参数为 APIs 启用二进制支持。 在 mime 类型中使用 ~1,而不是 /。

类型:列表

必需: 否

兼容性AWS CloudFormation:此属性类似于 BinaryMediaTypes 资源的 AWS::ApiGateway::RestApi 属性。的列表将添加到 BinaryMediaTypes 资源和 AWS CloudFormation 文档中。OpenAPI

CacheClusterEnabled

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

类型:布尔值

必需: 否

AWS CloudFormation 兼容性:此属性直接传递给 CacheClusterEnabled 资源的 AWS::ApiGateway::Stage 属性。

CacheClusterSize

阶段的缓存群集大小。

类型:字符串

必需: 否

兼容性AWS CloudFormation:此属性直接传递给 CacheClusterSize 资源的 AWS::ApiGateway::Stage 属性。

CanarySetting

将金丝雀版本设置配置为常规部署的阶段。

类型: CanarySetting

必需: 否

兼容性AWS CloudFormation:此属性直接传递给 CanarySetting 资源的 AWS::ApiGateway::Stage 属性。

Cors

管理所有 API Gateway 的跨源资源共享 (CORS) APIs。 指定要允许使用作为字符串的域,或使用其他 Cors 配置指定词典。注意:CORS 需要 AWS SAM 来修改您的 OpenAPI 定义。因此,仅当内联 OpenApi 是使用 DefinitionBody 定义的时,它才有效。

有关 CORS 的更多信息,请参阅 https://docs.amazonaws.cn/apigateway/latest/developerguide/how-to-cors.html 中的为 API Gateway REST API 资源启用 CORSAPI 网关 开发人员指南。

类型: String | CorsConfiguration

必需: 否

兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS CloudFormation。

DefinitionBody

描述您的 API 的 OpenAPI 规范。如果既未指定 DefinitionUri,也未指定 DefinitionBody,SAM 将根据您的模板配置为您生成 DefinitionBody

类型:字符串

必需: 否

兼容性AWS CloudFormation:此属性类似于 Body 资源的 AWS::ApiGateway::RestApi 属性。如果提供了某些属性,则在将内容传递到 DefinitionBody 之前,可能会向 CloudFormation 中插入或修改内容。 属性包括对应 AuthBinaryMediaTypesCorsGatewayResponsesModelsEventSource 以及 Api 类型的 AWS::Serverless::Function

DefinitionUri

AWS S3 Uri、本地文件路径或定义 API 的 OpenAPI 文档的位置对象。该属性引用的 AWS S3 对象必须是有效的 OpenAPI 文件。如果既未指定 DefinitionUri 也未指定 DefinitionBody,SAM 将根据您的模板配置为您生成 DefinitionBody

如果提供了本地文件路径,则模板必须执行包含 sam deploysam package 命令的工作流程,以便正确转换定义。

由 OpenApi 引用的外部 DefinitionUri 文件中不支持内部函数。 请改为将 DefinitionBody 属性与 Include Transform (包括转换) 结合使用,以将 OpenApi 定义导入到模板中。

类型: String | ApiDefinition

必需: 否

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

Description

Api 资源的描述。

类型:字符串

必需: 否

兼容性AWS CloudFormation:此属性直接传递给 Description 资源的 AWS::ApiGateway::RestApi 属性。

Domain

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

类型: DomainConfiguration

必需: 否

兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS CloudFormation。

EndpointConfiguration

REST API 的终端节点类型。

类型: EndpointConfiguration

必需: 否

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

GatewayResponses

为 API 配置网关响应。网关响应是由 API Gateway 返回的响应,可直接返回,也可以通过使用 Lambda 授权方返回。有关更多信息,请参阅适用于网关响应的 Api 网关 OpenApi 扩展的文档。

类型:Map

必需: 否

兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS CloudFormation。

MethodSettings

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

类型: MethodSettings

必需: 否

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

MinimumCompressionSize

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

类型:整数

必需: 否

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

Models

由您的 API 方法使用的架构。可以使用 JSON 或 YAML 描述这些架构。有关示例模型,请参阅此页面底部的“示例”部分。

类型:Map

必需: 否

兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS CloudFormation。

Name

API Gateway RestApi 资源的名称

类型:字符串

必需: 否

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

OpenApiVersion

要使用的 OpenApi 的版本。对于 Swagger 规范,这可以是 2.0,也可以是其中一个 OpenApi 3.0 版本(如 3.0.1)。 有关 OpenAPI 的更多信息,请参阅 OpenAPI 规范

注意:将该属性设置为任何有效值也将删除 SAM 创建的阶段 Stage

类型:字符串

必需: 否

兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS CloudFormation。

StageName

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

要引用阶段资源,请使用 <api-logical-id>.Stage。 有关引用在指定 AWS::Serverless::Api 资源时生成的资源的更多信息,请参阅AWS CloudFormation 指定AWS::Serverless::Api时生成的资源。有关生成的 AWS CloudFormation 资源的一般信息,请参阅已生成 AWS CloudFormation 资源

类型:字符串

必需: 是

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

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

Tags

指定要添加到此 API Gateway 阶段的标签的映射(字符串到字符串)。键和值仅限于字母数字字符。键的长度可以在 1 到 127 个 Unicode 字符之间,并且不能带有前缀 aws:值的长度可以是 1 到 255 个 Unicode 字符。

类型:Map

必需: 否

兼容性AWS CloudFormation:此属性类似于 Tags 资源的 AWS::ApiGateway::Stage 属性。SAM 中的 Tags 属性包含键值对;在 CloudFormation 中,它包含标签对象列表。

TracingEnabled

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

类型:布尔值

必需: 否

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

Variables

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

类型:Map

必需: 否

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

返回值

Ref

当向 Ref 内部函数提供该资源的逻辑 ID 时,它会返回底层 API 网关 API 的 ID。

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

Fn::GetAtt

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

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

RootResourceId

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

示例

SimpleApiExample

Hello World AWS SAM 模板文件,其中包含具有 API 终端节点的 Lambda 函数。这是适用于正常工作的无服务器应用程序的完整 AWS SAM 模板文件。

YAML

AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS 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

一个 AWS SAM 模板代码段,具有在外部 Swagger 文件以及 Lambda 集成和 CORS 配置中定义的 API。这只是 AWS 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

一个 AWS SAM 模板代码段,其中包含使用 AWS Cognito 针对 API 授权请求的 API。这只是 AWS 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

具有包含模型架构的 API 的 AWS SAM 模板代码段。这只是 AWS 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