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的规范。如果两者都不是 DefinitionUri 或 DefinitionBody 指定,SAM将生成 DefinitionBody 根据您的模板配置。

类型：字符串

必需: 否

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

DefinitionUri

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

如果提供了本地文件路径,则模板必须通过包含 sam deploy 或 sam 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 函数,请参阅 Ref 在 AWS 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