AWS::Serverless::Api

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

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的AWS::Serverless::Api不需要将资源明确添加到Amazon无服务器应用程序定义模板。这种类型的资源是根据上定义的 Api 事件的联合隐式创建的AWS::Serverless::Function模板中定义的未引用AWS::Serverless::Api资源。

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的AWS::Serverless::Api应使用资源来使用 OpenAPI 定义和记录 API，该 API 提供了配置底层 Amazon API Gateway 资源的更多功能。

Syntax

要在您的中声明此实体Amazon Serverless Application Model(Amazon 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
  Mode: String
  Models: Map
  Name: String
  OpenApiVersion: String
  StageName: String
  Tags: Map
  TracingEnabled: Boolean
  Variables: Map

Properties

AccessLogSetting

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

类型：AccessLogSetting

必需：否

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

Auth

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

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

类型：ApiAuth

必需：否

Amazon CloudFormation兼容性：对是唯一的。Amazon SAM没有Amazon CloudFormation等效函数

BinaryMediaTypes

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

类型：List

必需：否

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

CacheClusterEnabled

指示是否为阶段启用缓存群集。

类型：Boolean

必需：否

Amazon CloudFormation兼容性：此属性将直接传递给CacheClusterEnabled一个的财产AWS::ApiGateway::Stage资源。

CacheClusterSize

阶段的缓存群集大小。

类型：String

必需：否

Amazon CloudFormation兼容性：此属性将直接传递给CacheClusterSize一个的财产AWS::ApiGateway::Stage资源。

CanarySetting

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

类型：CanarySetting

必需：否

Amazon CloudFormation兼容性：此属性将直接传递给CanarySetting一个的财产AWS::ApiGateway::Stage资源。

Cors

管理所有 API Gateway API 的跨源资源共享 (CORS)。将允许的域指定为字符串，或者指定带有其他 Cos 配置的字典。注意：CORS 需要Amazon SAM以修改 OpenAPI 定义。因此，只有在使用 DineitionBody 定义了内联 OpenAPI 时，它才有效。

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

类型：字符串 |CorsConfiguration

必需：否

Amazon CloudFormation兼容性：对是唯一的。Amazon SAM没有Amazon CloudFormation等效函数

DefinitionBody

描述你的 API 的 OpenAPI 规范。如果都不是DefinitionUrinorDefinitionBody已指定，SAM 将生成DefinitionBody根据你的模板配置。

类型：String

必需：否

Amazon CloudFormation兼容性：此属性类似于Body一个的财产AWS::ApiGateway::RestApi资源。如果提供了某些属性，则可以在传递给 CloudFormation 之前将内容插入或修改到 DefintionBody 中。属性包括Auth、BinaryMediaTypes、Cors、GatewayResponses、Models，还有EventSource的类型为相应的 ApiAWS::Serverless::Function.

DefinitionUri

Amazon S3 Uri、本地文件路径或定义 OpenAPI 文档的位置对象。此属性引用的 Amazon S3 对象必须是有效的 OpenAPI 文件。如果都不是DefinitionUrinorDefinitionBody已指定，SAM 将生成DefinitionBody根据你的模板配置。

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

引用的外部 OpenAPI 文件不支持内在函数DefinitionUri. 请改用DefinitionBody房地产与包括转换将 OpenAPI 定义导入到模板中。

类型：字符串 |API 定义

必需：否

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

Description

Api 资源的描述。

类型：String

必需：否

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

Domain

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

类型：DomainConfiguration

必需：否

Amazon CloudFormation兼容性：对是唯一的。Amazon SAM没有Amazon CloudFormation等效函数

EndpointConfiguration

REST API 的终端节点类型。

类型：EndpointConfiguration

必需：否

Amazon CloudFormation兼容性：此属性类似于EndpointConfiguration一个的财产AWS::ApiGateway::RestApi资源。嵌套配置属性的命名方式不同。

GatewayResponses

为 API 配置网关响应。网关响应是 API Gateway 直接或通过使用 Lambda 授权方返回的响应。有关更多信息，请参阅用于网关响应的 API 网关 OpenAPI 扩展.

类型：Map

必需：否

Amazon CloudFormation兼容性：对是唯一的。Amazon SAM没有Amazon CloudFormation等效函数

MethodSettings

配置 API 阶段的所有设置，包括日志记录、指标、cachettl 和限制。

类型：MethodSettings

必需：否

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

MinimumCompressionSize

允许根据客户端的 Accept-Encode 标头压缩响应正文。当响应正文大小大于或等于您配置的阈值时，将触发压缩。最大正文大小阈值为 10 MB（10,485,760 字节）。-支持以下压缩类型：gzip、缩减和身份。

类型：整数

必需：否

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

Mode

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

有效值：overwrite 或 merge

类型：String

必需：否

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

Models

API 方法要使用的模式。这些模式可以使用 JSON 或 YAML 进行描述。有关示例模型，请参阅该页面底部的示例部分。

类型：Map

必需：否

Amazon CloudFormation兼容性：对是唯一的Amazon SAM没有Amazon CloudFormation等效函数

Name

API Gateway RestApi 资源的名称

类型：String

必需：否

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

OpenApiVersion

要使用的 OpenAPI 版本。这可以是2.0对于 Swagger 规范或 OpenAPI 3.0 版本之一，例如3.0.1. 有关 OpenAPI 的更多信息，请参阅OpenAPI 规格.

注意：将此属性设置为任何有效值也将删除舞台StageSAM 创造的。

类型：String

必需：否

Amazon CloudFormation兼容性：对是唯一的Amazon SAM没有Amazon CloudFormation等效函数

StageName

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

要引用舞台资源，请使用<api-logical-id>.Stage. 有关引用以下情况下生成的资源的更多信息。AWS::Serverless::Api已指定资源，请参阅Amazon CloudFormation指定 aws:: Serverless። Api 时生成的资源. 有关生成的一般信息Amazon CloudFormation资源，请参阅生成Amazon CloudFormationresources.

类型：String

必需：是

Amazon CloudFormation兼容性：此属性类似于StageName的财产AWS::ApiGateway::Stage资源。它在 SAM 中是必需的，但在 API Gateway 中不是必需的

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

Tags

一个映射（字符串到字符串），指定要添加到该 API Gateway 阶段的标签。有关标签的有效密钥和值的详细信息，请参阅资源标签中的 Amazon CloudFormation 用户指南.

类型：Map

必需：否

Amazon CloudFormation兼容性：此属性类似于Tags的财产AWS::ApiGateway::Stage资源。SAM 中的 Tags 属性由键:Value 对组成；在 CloudFormation 中，它由标签对象的列表组成。

TracingEnabled

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

类型：Boolean

必需：否

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

Variables

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

类型：Map

必需：否

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

返回值

Ref

当该资源的逻辑 ID 提供给Ref内在函数，它返回底层 API Gateway API 的 ID。

有关如何使用的更多信息Ref函数，请参阅Ref中的 Amazon CloudFormation 用户指南.

Fn::GetAtt

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

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

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

Examples

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

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的Amazon SAM模板片段，其中包含在外部 Swagger 文件中定义的 API 以及 Lambda 集成和 CORS 配置。这只是一个版本的一部分Amazon 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

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的Amazon SAM带有使用 Amazon Cognito 授权针对 API 的请求的 API 的模板片段。这只是一个版本的一部分Amazon 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

网络 ACL 和安全组都允许 (因此可到达您的实例) 的发起 ping 的Amazon SAM带有包含模型架构的 API 的模板片段。这只是一个版本的一部分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

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

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

资源和属性参考

ApiAuth