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应该使用资源来定义和记录 API OpenApi，它提供了配置底层Amazon API Gateway 资源的更多功能。

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

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

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

语法

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

YAML


Type: AWS::Serverless::Api
Properties:
  AccessLogSetting: AccessLogSetting
  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
  MethodSettings: MethodSettings
  MinimumCompressionSize: Integer
  Mode: String
  Models: Map
  Name: String
  OpenApiVersion: String
  StageName: String
  Tags: Map
  TracingEnabled: Boolean
  Variables: Map

属性

AccessLogSetting

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

类型：AccessLogSetting

必需：否

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

ApiKeySourceType

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

类型：字符串

必需：否

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

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

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

类型：布尔值

必需：否

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

CacheClusterSize

阶段的缓存群集大小。

类型：字符串

必需：否

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

CanarySetting

将 canary 设置配置为常规部署的某个阶段。

类型：CanarySetting

必需：否

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

Cors

管理所有 API Gateway API 的跨源资源共享 (CORS)。将允许的域指定为字符串或使用其他 Cors 配置指定字典。注意：CORS 需要Amazon SAM以修改您的 OpenAPI 定义。所以，它只有在内联时才起作用 OpenApi 定义为 DefinitionBody.

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

类型：字符串 |CorsConfiguration

必需：否

Amazon CloudFormation兼容性：此属性对是唯一的Amazon SAM而且不提供Amazon CloudFormation等效函数。

DefinitionBody

描述你的 API 的 OpenAPI 规范。如果两者都没有DefinitionUri也不DefinitionBody指定后，SAM 将生成一个DefinitionBody根据您的模板配置为您提供。

类型：JSON

必需：否

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

DefinitionUri

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

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

外部不支持内部函数 OpenApi 由引用了文件DefinitionUri. 请改用DefinitionBody属性带有包括转换导入 OpenApi 定义到模板中。

类型：字符串 |ApiDefinition

必需：否

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

Description

Api 资源的描述。

类型：字符串

必需：否

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

DisableExecuteApiEndpoint

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

类型：布尔值

必需：否

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

Domain

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

类型：DomainConfiguration

必需：否

Amazon CloudFormation兼容性：此属性对是唯一的Amazon SAM而且不提供Amazon CloudFormation等效函数。

EndpointConfiguration

REST API 的终端节点类型。

类型：EndpointConfiguration

必需：否

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

FailOnWarnings

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

类型：布尔值

必需：否

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

GatewayResponses

配置 API 的网关响应。网关响应是 API Gateway 直接或通过使用 Lambda 授权方返回的响应。有关更多信息，请参阅文档。Ap网关 OpenApi 网响应.

类型：映射

必需：否

Amazon CloudFormation兼容性：此属性对是唯一的Amazon SAM而且不提供Amazon CloudFormation等效函数。

MethodSettings

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

类型：MethodSettings

必需：否

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

MinimumCompressionSize

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

类型：整数

必需：否

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

Mode

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

有效值：overwrite 或 merge

类型：字符串

必需：否

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

Models

您的 API 方法要使用的架构。可以使用 JON 格式或 YAML 描述这些模式。有关示例模型的更多信息，请参阅本页底部的示例部分。

类型：映射

必需：否

Amazon CloudFormation兼容性：此属性对是唯一的Amazon SAM而且不提供Amazon CloudFormation等效函数。

Name

API Gateway 的名称 RestApi 资源

类型：字符串

必需：否

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

OpenApiVersion

版本 OpenApi 来使用。此值可以是唯一的2.0对于 Swagger 规范，或者其中一个 OpenApi 3.0 版本，比如3.0.1. 有关 OpenAPI 的更多信息，请参阅。OpenAPI 规规规规.

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

类型：字符串

必需：否

Amazon CloudFormation兼容性：此属性对是唯一的Amazon SAM而且不提供Amazon CloudFormation等效函数。

StageName

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

要引用阶段资源，请使用<api-logical-id>.Stage. 有关引用的资源的更多信息，AWS::Serverless::Api资源已指定，请参阅Amazon CloudFormation指定 Amazon። Serverless። Api 时生成的资源. 有关的一般信息Amazon CloudFormation资源，请参阅生成Amazon CloudFormation资源.

类型：字符串

必需：是

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

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

Tags

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

类型：映射

必需：否

Amazon CloudFormation兼容性：此属性类似于Tags一个的财产AWS::ApiGateway::Stage资源。SAM 中的 Tags 属性由 Key: Value 对组成；在 CloudFormation 它包含Tag 对象的列表。

TracingEnabled

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

类型：布尔值

必需：否

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

Variables

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

类型：映射

必需：否

Amazon CloudFormation兼容性：此属性将直接传递给 DayVariables一个的财产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。

示例

SimpleApiExample

HelldAmazon 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

缓存示例

HelldAmazon SAM模板文件，其中包含带有 API 终端节点的 Lambda 函数。该 API 为一个资源和方法启用了缓存。有关缓存的更多信息，请参阅。启用 API 缓存以增强响应能力中的API Gateway 开发人员指南.

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