AWS::Serverless::Api

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

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

应使用AWS::Serverless::Api OpenApi资源来定义和记录 API，这样可以提供更多配置底层 Amazon API Gateway 资源的能力。

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

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

有关使用 IAM 策略的更多信息，请参阅 API Gateway 开发人员指南中的要求 API 路由获得授权。

注意

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

语法

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

YAML


Type: AWS::Serverless::Api
Properties:
  AccessLogSetting: AccessLogSetting
  AlwaysDeploy: Boolean
  ApiKeySourceType: String
  Auth: ApiAuth
  BinaryMediaTypes: List
  CacheClusterEnabled: Boolean
  CacheClusterSize: String
  CanarySetting: CanarySetting
  Cors: String | CorsConfiguration
  DefinitionBody: JSON
  DefinitionUri: String | ApiDefinition
  Description: String
  DisableExecuteApiEndpoint: Boolean
  Domain: DomainConfiguration
  EndpointConfiguration: EndpointConfiguration
  FailOnWarnings: Boolean
  GatewayResponses: Map
  MergeDefinitions: Boolean
  MethodSettings: MethodSettings
  MinimumCompressionSize: Integer
  Mode: String
  Models: Map
  Name: String
  OpenApiVersion: String
  StageName: String
  Tags: Map
  TracingEnabled: Boolean
  Variables: Map

属性

AccessLogSetting

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

类型：AccessLogSetting

必需：否

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

AlwaysDeploy

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

类型：布尔值

必需：否

Amazon CloudFormation兼容性：此属性是唯一的Amazon SAM，没有Amazon CloudFormation等效属性。

ApiKeySourceType

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

类型：字符串

必需：否

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

指示是否为阶段启用缓存。要缓存响应，还必须将设置CachingEnabled为 untrue derMethodSettings。

类型：布尔值

必需：否

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 配置指定字典。注意：CORSAmazon SAM 需要修改你的 OpenAPI 定义。因此，只有使用定义行内时 OpenApi ，它才有效 DefinitionBody。

有关 CORS 的更多信息，请参阅 API Gateway 开发者指南中的 API Gateway REST API 资源启用 CORS。

类型：字符串 | CorsConfiguration

必需：否

Amazon CloudFormation兼容性：此属性是唯一的Amazon SAM，没有Amazon CloudFormation等效属性。

DefinitionBody

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

类型：JSON

必需：否

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

DefinitionUri

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

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

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

类型：字符串 | ApiDefinition

必需：否

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

Description

对 Api 资源的描述。

类型：字符串

必需：否

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

DisableExecuteApiEndpoint

指定客户端是否可以使用默认 execute-api 端点调用您的 API。默认情况下，客户端可以使用默认设置调用您的 APIhttps://{api_id}.execute-api.{region}.amazonaws.com。如果要求客户端使用自定义域名来调用 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

指定在遇到警告时回滚 API 创建 (true) 或不回滚 API 创建 (false)。默认值为 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规范。指定将其Amazon SAM合并true到AWS::Serverless::Api资源中定义的行内OpenAPI规范中。指定false不合并。

MergeDefinitions需要定义AWS::Serverless::Api的DefinitionBody属性。 MergeDefinitions与的DefinitionUri属性不兼容AWS::Serverless::Api。

默认值：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资源类型的模式属性。

有效值：overwrite 或 merge

类型：字符串

必需：否

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等效属性。

StageName

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

要引用舞台资源，请使用<api-logical-id>.Stage。有关引用指定资源时生成的AWS::Serverless::Api资源的更多信息，请参阅Amazon CloudFormation指定 Amazon። Serverless። Api 时生成的资源。有关生成的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函数的更多信息，请参阅Ref《Amazon CloudFormation用户指南》。

Fn::GetAtt

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

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

RootResourceId: RestApi 资源的根资源 ID，例如 a0bc123d4e。

示例

SimpleApiExample

一个 Hello WorldAmazon 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 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

一个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 WorldAmazon 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
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      CacheClusterEnabled: true
      CacheClusterSize: '0.5'
      MethodSettings:
        - ResourcePath: /
          HttpMethod: GET
          CachingEnabled: true
          CacheTtlInSeconds: 300

  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}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

资源和属性参考

ApiAuth