本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
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) 模板时,请使用以下语法。
YAML
Type: AWS::Serverless::Api Properties: AccessLogSetting:
AccessLogSetting
Auth:ApiAuth
BinaryMediaTypes:List
CacheClusterEnabled:Boolean
CacheClusterSize:String
CanarySetting:CanarySetting
Cors:String | CorsConfiguration
DefinitionBody:String
DefinitionUri:String | ApiDefinition
Description:String
Domain:DomainConfiguration
EndpointConfiguration:EndpointConfiguration
GatewayResponses:Map
MethodSettings:MethodSettings
MinimumCompressionSize:Integer
Models:Map
Name:String
OpenApiVersion:String
StageName:String
Tags:Map
TracingEnabled:Boolean
Variables:Map
属性
-
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 中插入或修改内容。 属性包括对应Auth
的BinaryMediaTypes
、Cors
、GatewayResponses
、Models
、EventSource
以及 Api 类型的AWS::Serverless::Function
。 -
DefinitionUri
-
AWS S3 Uri、本地文件路径或定义 API 的 OpenAPI 文档的位置对象。该属性引用的 AWS S3 对象必须是有效的 OpenAPI 文件。如果既未指定
DefinitionUri
也未指定DefinitionBody
,SAM 将根据您的模板配置为您生成DefinitionBody
。如果提供了本地文件路径,则模板必须执行包含
sam deploy
或sam 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 配置自定义域。
必需: 否
兼容性AWS CloudFormation:此属性对于 AWS SAM 是唯一的,没有等效的 AWS CloudFormation。
-
EndpointConfiguration
-
REST API 的终端节点类型。
必需: 否
兼容性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) 中的第一个路径分段。
要引用阶段资源,请使用
。 有关引用在指定 AWS::Serverless::Api 资源时生成的资源的更多信息,请参阅AWS CloudFormation 指定AWS::Serverless::Api时生成的资源。有关生成的 AWS CloudFormation 资源的一般信息,请参阅已生成 AWS CloudFormation 资源。<api-logical-id>
.Stage类型:字符串
必需: 是
兼容性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
函数的更多信息,请参阅 中的 Ref
AWS CloudFormation 用户指南。
Fn::GetAtt
Fn::GetAtt
返回一个此类型指定属性的值。以下为可用属性和示例返回值。
有关使用 Fn::GetAtt
的更多信息,请参阅 Fn::GetAtt
AWS CloudFormation 用户指南 中的 。
示例
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