AWS::Serverless::Api - AWS Serverless Application Model
语法属性返回值示例
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

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

AWS::Serverless::Api

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

无需将 AWS::Serverless::Api 资源显式添加到 AWS 无服务器应用程序定义模板中。此类型的资源是隐式从在不引用 AWS::Serverless::Function 资源的模板中定义的 AWS::Serverless::Api 资源上定义的 Api 事件联合创建的。

资源应该用于定义和记录使用 AWS::Serverless::Api 的 API，它提供了配置底层 Amazon API Gateway 资源的更强大的功能。OpenApi

语法

在您的 中声明此实体 AWS 无服务器应用程序模型 （AWS SAM） 模板时，请使用以下语法。

属性

AccessLogSetting

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

类型: AccessLogSetting

必需: 否

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

Auth

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

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

类型: 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

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

类型: CanarySetting

必需: 否

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

Cors

管理所有 API Gateway 的跨源资源共享 （CORS） APIs。 指定要允许使用作为字符串的域，或使用其他 Cors 配置指定词典。注意：CORS 需要 AWS SAM 来修改您的 OpenAPI 定义。因此，仅当内联 OpenApi 是使用 DefinitionBody 定义的时，它才有效。

有关 CORS 的更多信息，请参阅 https://docs.amazonaws.cn/apigateway/latest/developerguide/how-to-cors.html 中的为 API Gateway REST API 资源启用 CORSAPI 网关 开发人员指南。

类型： String | CorsConfiguration

必需: 否

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

DefinitionBody

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

类型：字符串

必需: 否

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

DefinitionUri

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

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

由 OpenApi 引用的外部 DefinitionUri 文件中不支持内部函数。 请改为将 DefinitionBody 属性与 Include Transform （包括转换） 结合使用，以将 OpenApi 定义导入到模板中。

类型： String | ApiDefinition

必需: 否

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

Description

Api 资源的描述。

类型：字符串

必需: 否

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

Domain

为此 API 网关 API 配置自定义域。

类型: DomainConfiguration

必需: 否

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

EndpointConfiguration

REST API 的终端节点类型。

类型: EndpointConfiguration

必需: 否

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

GatewayResponses

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

类型：Map

必需: 否

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

MethodSettings

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

类型: MethodSettings

必需: 否

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

MinimumCompressionSize

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

类型：整数

必需: 否

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

Models

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

类型：Map

必需: 否

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

Name

API Gateway RestApi 资源的名称

类型：字符串

必需: 否

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

OpenApiVersion

要使用的 OpenApi 的版本。对于 Swagger 规范，这可以是 2.0，也可以是其中一个 OpenApi 3.0 版本（如 3.0.1）。 有关 OpenAPI 的更多信息，请参阅 OpenAPI 规范。

注意：将该属性设置为任何有效值也将删除 SAM 创建的阶段 Stage。

类型：字符串

必需: 否

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

StageName

阶段的名称，API Gateway 将它用作调用统一资源标识符 （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 Gateway 中不是必需的

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

Tags

指定要添加到此 API Gateway 阶段的标签的映射（字符串到字符串）。键和值仅限于字母数字字符。键的长度可以在 1 到 127 个 Unicode 字符之间，并且不能带有前缀 aws：值的长度可以是 1 到 255 个 Unicode 字符。

类型：Map

必需: 否

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

TracingEnabled

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

类型：布尔值

必需: 否

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

Variables

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

类型：Map

必需: 否

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

返回值

Ref

当向 Ref 内部函数提供该资源的逻辑 ID 时，它会返回底层 API 网关 API 的 ID。

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

Fn::GetAtt

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

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

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 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 文件以及 Lambda 集成和 CORS 配置中定义的 API。这只是 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 模板代码段，其中包含使用 AWS Cognito 针对 API 授权请求的 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

具有包含模型架构的 API 的 AWS SAM 模板代码段。这只是 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