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

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

AWS::Serverless::Api

创建可通过HTTPS端点调用的AmazonAPI网关资源和方法集合。

一种 AWS::Serverless::Api 资源无需明确添加到AWS无服务器应用程序定义模板。此类型的资源是隐式从中定义的Api事件联合创建的 AWS::Serverless::Function 模板中定义的资源,这些资源未引用 AWS::Serverless::Api 资源。

一种 AWS::Serverless::Api 资源应用于定义和记录API OpenApi,这提供了更多配置底层AmazonAPI网关资源的能力。

语法

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

属性

AccessLogSetting

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

类型: AccessLogSetting

必需: 否

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

Auth

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

有关使用配置访问的更多信息 AWS SAM 参见 控制对的访问 API 网关 APIs 在 AWS 无服务器应用程序模型 开发人员指南.

类型: 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

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

类型: CanarySetting

必需: 否

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

Cors

管理所有API网关的跨源资源共享(CORS) APIs。指定域以允许作为字符串或指定具有其他Cors配置的字典。注意:CORS需要 AWS SAM 修改您的 OpenAPI 定义。因此,只有当内联 OpenApi 定义为 DefinitionBody.

有关CORS的更多信息,请参阅 为API网关RESTAPI资源启用CORS AmazonAPIGatewayDeveloperGuide中的。

类型:字符串| CorsConfiguration

必需: 否

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

DefinitionBody

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

类型:字符串

必需: 否

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

DefinitionUri

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

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

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

类型:字符串| ApiDefinition

必需: 否

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

Domain

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

类型: DomainConfiguration

必需: 否

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

EndpointConfiguration

RESTAPI的端点类型。

类型: EndpointConfiguration

必需: 否

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

GatewayResponses

为API配置网关响应。GatewayResponses(网关响应)是由APIGateway直接或通过Lambda授权器返回的响应。有关详细信息,请参阅文档 Api网关 OpenApi GatewayResponses分机.

类型:Map

必需: 否

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

MethodSettings

配置API阶段的所有设置,包括日志记录、度量标准、 CacheTTL,调节。

类型: MethodSettings

必需: 否

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

MinimumCompressionSize

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

类型:整数

必需: 否

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

Models

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

类型:Map

必需: 否

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

Name

API网关的名称 RestApi 资源

类型:字符串

必需: 否

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

OpenApiVersion

版本 OpenApi 使用。这可以是 2.0 Swagger规范,或 OpenApi 3.0版本,如 3.0.1。有关 OpenAPI,请参阅 OpenAPI 规格.

注意:将此属性设置为任何有效值也将移除阶段 Stage SAM创建。

类型:字符串

必需: 否

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

StageName

API网关在调用统一资源标识符(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网关中不是必需的

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

Tags

指定要添加到此API网关环节的标记的映射(字符串到字符串)。键和值限于个字母数字字符。密钥的长度可以是1至127个Unicode字符,不能以aws前缀:。数值可以是1至255个Unicode字符。

类型:Map

必需: 否

AWS CloudFormation 兼容性: 该属性类似于 Tags 属性 AWS::ApiGateway::Stage 资源。SAM中的“标记”属性由键:值对组成; CloudFormation 它由标记对象的列表组成。

TracingEnabled

指示是否使用 X-Ray 为阶段启用了。有关 X-Ray,请参阅 跟踪用户请求至REST APIs 使用 X-Ray 在 API 网关 开发者指南.

类型:布尔值

必需: 否

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

Variables

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

类型:Map

必需: 否

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

返回值

Ref

当此资源的逻辑ID提供给 Ref 内在函数,返回基础 API 网关 API。

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

Fn::GetAtt

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

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

RootResourceId

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

示例

SimpleApiExample

一个HelloWorld 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文件中定义的API以及Lambda集成和CORS配置。这只是 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 模板片段,API使用AWSCognito来针对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

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