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

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

AWS::Serverless::Api

创建一组可通过 HTTPS 端点调用的 Amazon API Gateway 资源和方法。

无需将AWS::Serverless::Api资源明确添加到 Amazon 无服务器应用程序定义模板中。这种类型的资源是通过 AWS::Serverless::Function 资源上定义的 Api 事件的并集隐式创建的,这些资源定义于未引用 AWS::Serverless::Api 资源的模板。

应使用AWS::Serverless::Api资源来定义和记录 API OpenApi,这样可以更好地配置底层 Amazon API Gateway 资源。

我们建议您使用 Amazon CloudFormation 挂钩或 IAM 策略来验证 API Gateway 资源是否附加了授权者来控制对它们的访问。

有关使用 Amazon CloudFormation 挂钩的更多信息,请参阅 Amazon CloudFormation CLI 用户指南apigw-enforce-authorizer GitHub 存储库中的注册挂钩

有关使用 IAM 策略的更多信息,请参阅《API Gateway 开发人员指南》中的要求 API 路由具有授权

注意

部署到时 Amazon CloudFormation, Amazon SAM 会将您的 Amazon SAM 资源转换为 Amazon CloudFormation 资源。有关更多信息,请参阅生成的 Amazon CloudFormation 资源

语法

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

属性

AccessLogSetting

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

类型:AccessLogSetting

必需:否

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

AlwaysDeploy

即使未检测到 API 的更改,也要始终部署 API。

类型:布尔值

必需:否

Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。

ApiKeySourceType

用于根据使用计划对请求进行计量的 API 键的源。有效值为 HEADERAUTHORIZER

类型:字符串

必需:否

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

Auth

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

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

类型:ApiAuth

必需:否

Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。

BinaryMediaTypes

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

类型:列表

必需:否

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

CacheClusterEnabled

指示是否为阶段启用缓存。要缓存响应,还必须在 MethodSettings 下将 CachingEnabled 设置为 true

类型:布尔值

必需:否

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

CacheClusterSize

阶段的缓存群集大小。

类型:字符串

必需:否

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

CanarySetting

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

类型:CanarySetting

必需:否

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

Cors

管理所有 API Gateway API 的跨源资源共享 (CORS)。使用字符串指定允许使用的域,或使用其他 Cors 配置指定词典。

注意

CORS Amazon SAM 需要修改你的 OpenAPI 定义。在中创建一个内联 OpenAPI 定义DefinitionBody以启用 CORS。

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

类型:字符串 | CorsConfiguration

必需:否

Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。

DefinitionBody

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

要引用定义 API 的本地 OpenAPI 文件,请使用 AWS::Include 转换。要了解更多信息,请参阅在部署时上传本地文件

类型:JSON

必需:否

Amazon CloudFormation 兼容性:此属性类似于AWS::ApiGateway::RestApi资源的Body属性。如果提供了某些属性,则可以在将内容传递给DefinitionBody 之前在中插入或修改内容 CloudFormation。属性包括 AuthBinaryMediaTypesCorsGatewayResponsesModels、和 AWS::Serverless::Function 相应 Api 类型的 EventSource

DefinitionUri

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

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

引用的外部 OpenApi 文件不支持内部函数。DefinitionUri改用带有 Include 转换DefinitionBody属性将 OpenApi 定义导入到模板中。

类型:字符串 | ApiDefinition

必需:否

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

Description

Api 资源的描述。

类型:字符串

必需:否

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

DisableExecuteApiEndpoint

指定客户端是否可以使用默认 execute-api 端点调用您的 API。默认情况下,客户端可以使用默认 https://{api_id}.execute-api.{region}.amazonaws.com 调用您的 API。如果要求客户端使用自定义域名来调用 API,请指定 True

类型:布尔值

必需:否

Amazon CloudFormation 兼容性:此属性类似于AWS::ApiGateway::RestApi资源的 DisableExecuteApiEndpoint属性。它直接传递给 x-amazon-apigateway-endpoint-configuration 扩展的 disableExecuteApiEndpoint 属性,然后添加到 AWS::ApiGateway::RestApi 资源的 Body 属性中。

Domain

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

类型:DomainConfiguration

必需:否

Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。

EndpointConfiguration

REST API 的端点类型。

类型:EndpointConfiguration

必需:否

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

FailOnWarnings

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

类型:布尔值

必需:否

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

GatewayResponses

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

类型:映射

必需:否

Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。

MergeDefinitions

Amazon SAM 从您的 API 事件源生成OpenAPI规范。指定true将其 Amazon SAM 合并到AWS::Serverless::Api资源中定义的内联OpenAPI规范中。指定 false 以不合并。

MergeDefinitions 需要定义 AWS::Serverless::ApiDefinitionBody 属性。MergeDefinitionsAWS::Serverless::ApiDefinitionUri 属性不兼容。

默认值false

类型:布尔值

必需:否

Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。

MethodSettings

配置 API 阶段的所有设置,包括日志、指标、CacheTTL、节流。

类型 MethodSetting 列表

必需:否

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

MinimumCompressionSize

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

类型:整数

必需:否

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

Mode

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

有效值overwritemerge

类型:字符串

必需:否

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

Models

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

类型:映射

必需:否

Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。

Name

API Gateway RestApi 资源的名称

类型:字符串

必需:否

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

OpenApiVersion

OpenApi 要使用的版本。这可以是 2.0 Swagger 规范,也可以是 OpenApi 3.0 版本之一,比如。3.0.1有关 OpenAPI 的更多信息,请参阅 OpenAPI 规范

注意

Amazon SAM 创建一个默认情况下名为Stage的阶段。将此属性设置为任何有效值将阻止阶段 Stage 的创建。

类型:字符串

必需:否

Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。

PropagateTags

指明是否将 Tags 属性中的标签传递给 AWS::Serverless::Api 生成的资源。指定 True 以在生成的资源中传播标签。

类型:布尔值

必需:否

默认值False

Amazon CloudFormation 兼容性:此属性是独有的 Amazon SAM ,没有 Amazon CloudFormation 等效属性。

StageName

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

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

类型:字符串

必需:是

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

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

Tags

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

类型:映射

必需:否

Amazon CloudFormation 兼容性:此属性类似于AWS::ApiGateway::Stage资源的Tags属性。SAM 中的 Tags 属性由 Key: Value CloudFormation 对组成;其中包含标签对象的列表。

TracingEnabled

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

类型:布尔值

必需:否

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

Variables

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

类型:映射

必需:否

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

返回值

Ref

当向 Ref 内置函数提供此资源的逻辑 ID 时,它将返回底层 API Gateway API 的 ID。

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

Fn:: GetAtt

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

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

RootResourceId

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

示例

SimpleApiExample

一个 Hello World Amazon 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 method at the root resource via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.10 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200}

ApiCorsExample

一个 Amazon SAM 模板片段,其中包含在外部 Swagger 文件中定义的 API 以及 Lambda 集成和 CORS 配置。这只是显示AWS::Serverless::Api定义的 Amazon SAM 模板文件的一部分。

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

包含使用 Amazon Cognito 授权针对该 API 的请求的 API 的 Amazon SAM 模板片段。这只是显示AWS::Serverless::Api定义的 Amazon SAM 模板文件的一部分。

YAML

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

ApiModelsExample

带有包含模型架构的 API 的 Amazon SAM 模板片段。这只是 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

缓存示例

一个 Hello World Amazon SAM 模板文件,其中包含带有 API 端点的 Lambda 函数。API 已为一种资源和方法启用缓存。有关缓存的更多信息,请参阅的《API Gateway 开发人员指南》中的启用 API 缓存以增强响应能力

YAML

AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 Description: AWS SAM template with a simple API definition with caching turned on Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: prod CacheClusterEnabled: true CacheClusterSize: '0.5' MethodSettings: - ResourcePath: / HttpMethod: GET CachingEnabled: true CacheTtlInSeconds: 300 Tags: CacheMethods: All ApiFunction: # Adds a GET method at the root resource via an Api event Type: AWS::Serverless::Function Properties: Events: ApiEvent: Type: Api Properties: Path: / Method: get RestApiId: Ref: ApiGatewayApi Runtime: python3.10 Handler: index.handler InlineCode: | def handler(event, context): return {'body': 'Hello World!', 'statusCode': 200}