AWS::Serverless::Api - AWS Serverless Application Model
语法属性返回值示例

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

AWS::Serverless::Api

创建一组可通过 HTTPS 端点调用的 Amazon API Gateway 资源和方法。

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

应使用 AWS::Serverless::Api 资源通过 OpenAPI 定义和记录 API，这为配置底层 Amazon API Gateway 资源提供了更多功能。

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

有关使用 AWS CloudFormation 钩子的更多信息，请参阅《AWS CloudFormation CLI 用户指南》中的注册钩子和 apigw-enforce-authorizer GitHub 存储库。

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

注意

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

语法

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

属性

AccessLogSetting

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

类型：AccessLogSetting

必需：否

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

AlwaysDeploy

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

类型：布尔值

必需：否

AWS CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 AWS CloudFormation 等效属性。

ApiKeySourceType

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

类型：字符串

必需：否

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

Auth

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

有关使用 AWS SAM 配置访问权限的更多信息，请参阅 使用 AWS SAM 模板控制 API 访问。

类型：ApiAuth

必需：否

AWS CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 AWS CloudFormation 等效属性。

BinaryMediaTypes

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

类型：列表

必需：否

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

CacheClusterEnabled

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

类型：布尔值

必需：否

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

CacheClusterSize

阶段的缓存群集大小。

类型：字符串

必需：否

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

CanarySetting

将金丝雀设置配置为常规部署的某个阶段。

类型：CanarySetting

必需：否

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

Cors

管理所有 API Gateway API 的跨源资源共享 (CORS)。使用字符串指定允许使用的域，或使用其他 Cors 配置指定词典。

注意

CORS 要求 AWS SAM 修改 OpenAPI 定义。在 DefinitionBody 中创建内联 OpenAPI 定义以开启 CORS。

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

类型：字符串 | CorsConfiguration

必需：否

AWS CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 AWS CloudFormation 等效属性。

DefinitionBody

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

要引用定义 API 的本地 OpenAPI 文件，请使用 AWS::Include 转换。要了解更多信息，请参阅 如何 AWS SAM 上传本地文件。

类型：JSON

必需：否

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

DefinitionUri

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

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

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

类型：字符串 | ApiDefinition

必需：否

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

Description

Api 资源的描述。

类型：字符串

必需：否

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

DisableExecuteApiEndpoint

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

类型：布尔值

必需：否

AWS CloudFormation 兼容性：此属性类似于 AWS::ApiGateway::RestApi 资源的 DisableExecuteApiEndpoint 属性。它直接传递给 x-amazon-apigateway-endpoint-configuration 扩展的 disableExecuteApiEndpoint 属性，然后添加到 AWS::ApiGateway::RestApi 资源的 Body 属性中。

Domain

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

类型：DomainConfiguration

必需：否

AWS CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 AWS CloudFormation 等效属性。

EndpointConfiguration

REST API 的端点类型。

类型：EndpointConfiguration

必需：否

AWS CloudFormation 兼容性：此属性类似于 AWS::ApiGateway::RestApi 资源的 EndpointConfiguration 属性。嵌套配置属性的命名有所不同。

FailOnWarnings

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

类型：布尔值

必需：否

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

GatewayResponses

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

类型：映射

必需：否

AWS CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 AWS CloudFormation 等效属性。

MergeDefinitions

AWS SAM 会从您的 API 事件源生成 OpenAPI 规范。指定 true 以让 AWS SAM 将其合并到 AWS::Serverless::Api 资源中定义的内联 OpenAPI 规范中。指定 false 以不合并。

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

默认值：false

类型：布尔值

必需：否

AWS CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 AWS CloudFormation 等效属性。

MethodSettings

配置 API 阶段的所有设置，包括日志、指标、CacheTTL、节流。

类型：MethodSetting 列表

必需：否

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

MinimumCompressionSize

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

类型：整数

必需：否

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

Mode

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

有效值：overwrite 或 merge

类型：字符串

必需：否

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

Models

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

类型：映射

必需：否

AWS CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 AWS CloudFormation 等效属性。

Name

API Gateway RestApi 资源的名称

类型：字符串

必需：否

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

OpenApiVersion

要使用的 OpenApi 版本。这可以是 Swagger 规范 2.0，也可以是 OpenApi 3.0 版本之一，比如 3.0.1。有关 OpenAPI 的更多信息，请参阅 OpenAPI 规范。

注意

默认情况下，AWS SAM 会创建一个名为 Stage 的阶段。将此属性设置为任何有效值将阻止阶段 Stage 的创建。

类型：字符串

必需：否

AWS CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 AWS CloudFormation 等效属性。

PropagateTags

指明是否将 Tags 属性中的标签传递给 AWS::Serverless::Api 生成的资源。指定 True 以在生成的资源中传播标签。

类型：布尔值

必需：否

默认值：False

AWS CloudFormation 兼容性：此属性为 AWS SAM 独有，没有 AWS CloudFormation 等效属性。

StageName

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

要引用阶段资源，请使用 <api-logical-id>.Stage。有关指定 AWS::Serverless::Api 资源时引用生成资源的更多信息，请参阅 在指定了 AWS::Serverless::Api 的情况下生成的 AWS CloudFormation 资源。有关生成的 AWS CloudFormation 资源的一般信息，请参阅 为 AWS SAM 生成的 AWS CloudFormation 资源。

类型：字符串

必需：是

AWS CloudFormation 兼容性：此属性类似于 AWS::ApiGateway::Stage 资源的 StageName 属性。它在 SAM 中为必需，但在 API Gateway 中并非必需

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

Tags

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

类型：映射

必需：否

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

TracingEnabled

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

类型：布尔值

必需：否

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

Variables

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

类型：映射

必需：否

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

返回值

Ref

当向 Ref 内置函数提供此资源的逻辑 ID 时，它将返回底层 API Gateway API 的 ID。

有关使用 Ref 函数的更多信息，请参阅《AWS CloudFormation 用户指南》中的 Ref。

Fn::GetAtt

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

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

RootResourceId

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

示例

SimpleApiExample

Hello World 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 method at the root resource via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.10
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}

ApiCorsExample

AWS SAM 模板片段，其中包含在外部 Swagger 文件中定义的 API 以及 Lambda 集成和 CORS 配置。这只是显示 AWS::Serverless::Api 定义的 AWS 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

AWS SAM 模板片段，其中包含使用 Amazon Cognito 授权针对该 API 的请求的 API。这只是显示 AWS::Serverless::Api 定义的 AWS SAM 模板文件的一部分。

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

缓存示例

Hello World AWS 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 with caching turned on
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      CacheClusterEnabled: true
      CacheClusterSize: '0.5'
      MethodSettings:
        - ResourcePath: /
          HttpMethod: GET
          CachingEnabled: true
          CacheTtlInSeconds: 300
      Tags:
        CacheMethods: All 

  ApiFunction: # Adds a GET method at the root resource via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.10
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}