AWS::Serverless::Api

建立可透過 HTTPS 端點叫用的 Amazon API Gateway 資源和方法的集合。

資AWS::Serverless::Api源不需要明確新增至 AWS 無伺服器應用程式定義範本。這種類型的資源是從模板中定義的AWS::Serverless::Function資源上定義的不引用資源的 Api 事件聯集隱式創建的。AWS::Serverless::Api

應使用AWS::Serverless::Api資源來定義和記錄 API OpenApi，這可提供更多設定基礎 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 CloudFormation 資源 AWS SAM。

語法

若要在 AWS Serverless Application Model (AWS 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
  PropagateTags: Boolean
  StageName: String
  Tags: Map
  TracingEnabled: Boolean
  Variables: Map

屬性

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

指出是否為階段啟用快取。若要快取回應，您也必須CachingEnabled將設定為 true [下] MethodSettings。

類型：布林值

必要：否

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)。指定允許作為字符串的域或指定帶有其他 CRS 配置的字典。

注意

CORS 需要修 AWS SAM 改您的 OpenAPI 定義。在中建立內嵌 OpenAPI 定義以DefinitionBody開啟 CORS。

如需有關 CORS 的詳細資訊，請參閱 API Gateway 開發人員指南中的針對 API Gateway REST API 資源啟用 CO RS。

類型：字符串 | CorsConfiguration

必要：否

AWS CloudFormation 兼容性：此屬性是唯一的， AWS SAM 並且沒有相 AWS CloudFormation 等的屬性。

DefinitionBody

用於描述您的 API 的 OpenAPI 規範。如果沒有指定DefinitionUri也沒DefinitionBody有指定，SAM 將根據您DefinitionBody的模板配置為您生成一個。

若要參考定義 API 的本機OpenAPI檔案，請使用AWS::Include轉換。如需進一步了解，請參閱部署時上傳本機檔案。

類型：JSON

必要：否

AWS CloudFormation 兼容性：此屬性類似於AWS::ApiGateway::RestApi資源的Body屬性。如果提供了某些屬性，則可以在將內容插入或修改到中，然後DefinitionBody 再將內容傳遞給 CloudFormation。屬性包括AuthBinaryMediaTypesCors、GatewayResponses、Models、和類EventSource型為 Api 的對應AWS::Serverless::Function。

DefinitionUri

Amazon S3 Uri、本機檔案路徑或定義 OpenAPI 件的位置物件。此屬性參考的 Amazon S3 物件必須是有效的 OpenAPI 檔案。如果沒有指定DefinitionUri也沒DefinitionBody有指定，SAM 將根據您DefinitionBody的模板配置為您生成一個。

如果提供了本機檔案路徑，則範本必須經過包含sam deploy或sam package指令的工作流程，才能正確轉換定義。

所參考的外部 OpenApi 檔案不支援內建函式。DefinitionUri改為搭配「包含轉換」使用DefinitionBody屬性，將定 OpenApi 義匯入範本。

類型：字符串 | ApiDefinition

必要：否

AWS CloudFormation 兼容性：此屬性類似於AWS::ApiGateway::RestApi資源的BodyS3Location屬性。巢狀 Amazon S3 屬性的命名方式不同。

Description

Api 資源的描述。

類型：字串

必要：否

AWS CloudFormation 兼容性：此屬性直接傳遞給AWS::ApiGateway::RestApi資源的Description屬性。

DisableExecuteApiEndpoint

指定用戶端是否可以使用預設 execute-api 端點叫用您的 API。默認情況下，客戶端可以使用默認調用您的 API https://{api_id}.execute-api.{region}.amazonaws.com。如要要求用戶端使用自訂網域名稱來叫用 API，請指定 True。

類型：布林值

必要：否

AWS CloudFormation 兼容性：此屬性類似於AWS::ApiGateway::RestApi資源的 DisableExecuteApiEndpoint屬性。它會直接傳遞至擴充功能的disableExecuteApiEndpoint屬性，而 x-amazon-apigateway-endpoint-configuration擴充功能會新增至AWS::ApiGateway::RestApi資源的Body屬性。

Domain

設定此 API Gateway API 的自訂網域。

類型:DomainConfiguration

必要：否

AWS CloudFormation 兼容性：此屬性是唯一的， AWS SAM 並且沒有相 AWS CloudFormation 等的屬性。

EndpointConfiguration

其餘 API 的端點類型。

類型:EndpointConfiguration

必要：否

AWS CloudFormation 兼容性：此屬性類似於AWS::ApiGateway::RestApi資源的EndpointConfiguration屬性。巢狀組態屬性的命名方式不同。

FailOnWarnings

指定遇到警告時是否回滾 API 創建（truefalse）或不（）。預設值為 false。

類型：布林值

必要：否

AWS CloudFormation 兼容性：此屬性直接傳遞給AWS::ApiGateway::RestApi資源的FailOnWarnings屬性。

GatewayResponses

設定 API 的閘道回應。閘道回應是 API Gateway 直接或透過 Lambda 授權人傳回的回應。如需詳細資訊，請參閱閘道回應的 Api 閘道 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與的DefinitionUri屬性不相容AWS::Serverless::Api。

預設值：false

類型：布林值

必要：否

AWS CloudFormation 兼容性：此屬性是唯一的， AWS SAM 並且沒有相 AWS CloudFormation 等的屬性。

MethodSettings

配置 API 階段的所有設置，包括日誌記錄，指標，緩存，節流。

類型： MethodSetting 的清單

必要：否

AWS CloudFormation 兼容性：此屬性直接傳遞給AWS::ApiGateway::Stage資源的MethodSettings屬性。

MinimumCompressionSize

允許基於客戶端的接受編碼頭響應主體的壓縮。當回應主體大小大於或等於您設定的閾值時，就會觸發壓縮。最大主體大小閾值為 10 MB（10,485,760 字節）。-支援下列壓縮類型：gzip、放氣和識別。

類型：整數

必要：否

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 規範，也可以是 OpenApi 3.0 版本之一，2.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 CloudFormation 指定時產生AWS::Serverless::Api的資源。如需有關已產生 AWS CloudFormation 資源的一般資訊，請參閱產生的 AWS CloudFormation 資源 AWS SAM。

類型：字串

必要：是

AWS CloudFormation 兼容性：此屬性類似於AWS::ApiGateway::Stage資源的StageName屬性。它在 SAM 中是必需的，但在 API Gateway 中不是必需的

附加說明：隱式 API 的階段名稱為「Prod」。

Tags

映射（字符串到字符串），指定要添加到此 API Gateway 階段的標籤。如需有關標籤的有效鍵和值的詳細資訊，請參閱《AWS CloudFormation 使用指南》中的〈Resource 標籤〉。

類型：地圖

必要：否

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

將此資源的邏輯 ID 提供給Ref內建函數時，它會傳回基礎 API Gateway API 的識別碼。

若要取得有關使用Ref功能的更多資訊，請參閱《使AWS CloudFormation 用指南》Ref中的〈〉

Fn: GetAtt

Fn::GetAtt 會傳回此類型之指定屬性的值。以下為可用屬性及傳回值的範例。

若要取得有關使用的更多資訊Fn::GetAtt，請參閱使AWS CloudFormation 用指南Fn::GetAtt中的〈〉

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

範例

SimpleApiExample

包含具有 API 端點的 Lambda 函數的「你好世界」 AWS SAM 範本檔案。這是一個工作的無服務器應用程序的完整 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

在外部 Swagger 檔案中定義具有 API 的 AWS SAM 範本程式碼片段，以及 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

具有 API 的 AWS SAM 範本程式碼片段，該程式碼片段使用 Amazon Cognito 針對 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

緩存示例

包含具有 API 端點的 Lambda 函數的「你好世界」 AWS SAM 範本檔案。該 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}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

資源和屬性

ApiAuth