AWS::Serverless::HttpApi

建立 Amazon API Gateway HTTP API，這可讓您建立延遲較低且成本低於 REST API 的 RESTful APIs。 APIs 如需詳細資訊，請參閱APIs開發人員指南》中的使用 HTTP API。

我們建議您使用 CloudFormation 勾點或 IAM 政策來驗證 API Gateway 資源是否已連接授權方，以控制對它們的存取。

如需使用 CloudFormation 勾點的詳細資訊，請參閱 CloudFormation CLI 使用者指南中的註冊勾點和 apigw-enforce-authorizer GitHub 儲存庫。

如需使用 IAM 政策的詳細資訊，請參閱《 API Gateway 開發人員指南》中的要求 API 路由具有授權。

注意

當您部署到時 AWS CloudFormation，會將您的 AWS SAM 資源 AWS SAM 轉換為 CloudFormation 資源。如需詳細資訊，請參閱為產生 CloudFormation 資源 AWS SAM。

語法

若要在 AWS Serverless Application Model (AWS SAM) 範本中宣告此實體，請使用下列語法。

YAML


Type: AWS::Serverless::HttpApi
Properties:
  AccessLogSettings: AccessLogSettings
  Auth: HttpApiAuth
  CorsConfiguration: String | HttpApiCorsConfiguration
  DefaultRouteSettings: RouteSettings
  DefinitionBody: JSON
  DefinitionUri: String | HttpApiDefinition
  Description: String
  DisableExecuteApiEndpoint: Boolean
  Domain: HttpApiDomainConfiguration
  FailOnWarnings: Boolean
  Name: String
  PropagateTags: Boolean
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

Properties

AccessLogSettings

階段中存取記錄的設定。

類型：AccessLogSettings

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::ApiGatewayV2::Stage 資源的 AccessLogSettings 屬性。

Auth

設定授權以控制對 API Gateway HTTP API 的存取。

如需詳細資訊，請參閱《API Gateway 開發人員指南》中的使用 JWT 授權方控制對 HTTP API 的存取。

類型：HttpApiAuth

必要：否

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

CorsConfiguration

管理所有 API Gateway HTTP APIs 的跨來源資源共用 (CORS)。指定要允許做為字串的網域，或指定HttpApiCorsConfiguration物件。請注意，CORS 需要 AWS SAM 修改您的 OpenAPI 定義，因此 CORS 只有在指定 DefinitionBody 屬性時才有效。

如需詳細資訊，請參閱《 API Gateway 開發人員指南》中的設定 HTTP API 的 CORS。

注意

如果 CorsConfiguration 在 OpenAPI 定義和屬性層級同時設定，則 AWS SAM 會合併兩個組態來源，屬性優先。如果此屬性設定為 true，則允許所有原始伺服器。

類型：字串 | HttpApiCorsConfiguration

必要：否

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

DefaultRouteSettings

此 HTTP API 的預設路由設定。除非由特定路由的 RouteSettings 屬性覆寫，否則這些設定適用於所有路由。

類型：RouteSettings

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::ApiGatewayV2::Stage 資源的 RouteSettings 屬性。

DefinitionBody

描述 HTTP API 的 OpenAPI 定義。如果您未指定 DefinitionUri或 DefinitionBody，會根據範本組態DefinitionBody為您 AWS SAM 產生。

類型：JSON

必要：否

CloudFormation 相容性：此屬性類似於 AWS::ApiGatewayV2::Api 資源的 Body 屬性。如果提供特定屬性， AWS SAM 則可以在內容傳遞至 DefinitionBody之前，將內容插入或修改 CloudFormation。對應AWS::Serverless::Function資源EventSource的屬性包括 Auth和 HttpApi 類型的。

DefinitionUri

定義 HTTP API 之 OpenAPI 定義的 Amazon Simple Storage Service (Amazon S3) URI、本機檔案路徑或位置物件。此屬性參考的 Amazon S3 物件必須是有效的 OpenAPI 定義檔案。如果您未指定 DefinitionUri或DefinitionBody已指定，會根據範本組態DefinitionBody為您 AWS SAM 產生。

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

您使用參考的外部 OpenApi 定義檔案中不支援內部函數DefinitionUri。若要將 OpenApi 定義匯入範本，請使用 DefinitionBody 屬性搭配包含轉換。

類型：字串 | HttpApiDefinition

必要：否

CloudFormation 相容性：此屬性類似於 AWS::ApiGatewayV2::Api 資源的 BodyS3Location 屬性。巢狀 Amazon S3 屬性的名稱不同。

Description

HTTP API 資源的描述。

當您指定時Description， AWS SAM 將透過設定 description 欄位來修改 HTTP API 資源的 OpenApi 定義。下列案例將導致錯誤：

DefinitionBody 屬性是在開啟 API 定義中以 description 欄位集指定 – 這會導致 AWS SAM 無法解析description的欄位衝突。
屬性DefinitionUri已指定 – AWS SAM 不會修改從 Amazon S3 擷取的 Open API 定義。

類型：字串

必要：否

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

DisableExecuteApiEndpoint

指定用戶端是否可以使用預設execute-api端點叫用您的 HTTP APIhttps://{api_id}.execute-api.{region}.amazonaws.com。根據預設，用戶端可以使用預設端點叫用您的 API。若要要求用戶端僅使用自訂網域名稱來叫用您的 API，請停用預設端點。

若要使用此屬性，您必須在 OpenAPI 定義x-amazon-apigateway-endpoint-configurationdisableExecuteApiEndpoint中指定 DefinitionBody 屬性，而不是 DefinitionUri 屬性或使用定義。

類型：布林值

必要：否

CloudFormation 相容性：此屬性類似於 AWS::ApiGatewayV2::Api 資源的 DisableExecuteApiEndpoint 屬性。它會直接傳遞至 x-amazon-apigateway-endpoint-configuration延伸的 disableExecuteApiEndpoint 屬性，該延伸會新增至 AWS::ApiGatewayV2::Api 資源的 Body 屬性。

Domain

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

類型：HttpApiDomainConfiguration

必要：否

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

FailOnWarnings

指定在遇到警告時是否要轉返 HTTP API 建立 (true) 與否 (false)。預設值為 false。

類型：布林值

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::ApiGatewayV2::Api 資源的 FailOnWarnings 屬性。

Name

HTTP API 資源的名稱。

當您指定時Name， AWS SAM 將透過設定 title 欄位來修改 HTTP API 資源的 OpenAPI 定義。下列案例將導致錯誤：

DefinitionBody 屬性是在開啟 API 定義中以 title 欄位集指定 – 這會導致 AWS SAM 無法解析title的欄位衝突。
屬性DefinitionUri已指定 – AWS SAM 不會修改從 Amazon S3 擷取的 Open API 定義。

類型：字串

必要：否

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

PropagateTags

指出是否要將標籤從 Tags 屬性傳遞至您AWS::Serverless::HttpApi產生的資源。指定 True 在產生的資源中傳播標籤。

類型：布林值

必要：否

預設：False

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

RouteSettings

此 HTTP API 每個路由的路由設定。如需詳細資訊，請參閱APIs》中的使用 HTTP API 的路由。

類型：RouteSettings

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::ApiGatewayV2::Stage 資源的 RouteSettings 屬性。

StageName

API 階段的名稱。如果未指定名稱， AWS SAM 會使用來自 API Gateway 的 $default階段。

類型：字串

必要：否

預設：$default

CloudFormation 相容性：此屬性會直接傳遞至 AWS::ApiGatewayV2::Stage 資源的 StageName 屬性。

StageVariables

定義階段變數的映射。變數名稱可以包含英數字元和底線字元。這些值必須符合【A-Za-z0-9-._~：/？#&=，】＋。

類型：Json

必要：否

CloudFormation 相容性：此屬性會直接傳遞至 AWS::ApiGatewayV2::Stage 資源的 StageVariables 屬性。

Tags

映射（字串到字串），指定要新增至此 API Gateway 階段的標籤。金鑰長度可以是 1 到 128 個 Unicode 字元，且不能包含字首 aws:。您可以使用以下任何字元：Unicode 字母、數字、空格、_、.、/、=、+ 和 - 的組合。值長度可以是 1 到 256 個 Unicode 字元。

類型：映射

必要：否

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

其他備註： Tags 屬性需要 AWS SAM 修改您的 OpenAPI 定義，因此只有在指定 DefinitionBody 屬性時才會新增標籤 - 如果指定 DefinitionUri 屬性，則不會新增標籤。 AWS SAM 自動新增httpapi:createdBy:SAM標籤。標籤也會新增至AWS::ApiGatewayV2::Stage資源和資源 AWS::ApiGatewayV2::DomainName（如果DomainName已指定）。

傳回值

Ref

當您將此資源的邏輯 ID 傳遞至內部 Ref函數時，便會Ref傳回基礎AWS::ApiGatewayV2::Api資源的 API ID，例如 a1bcdef2gh。

如需使用 Ref函數的詳細資訊，請參閱AWS CloudFormation 《使用者指南Ref》中的。

範例

簡易 HttpApi

下列範例顯示設定由 Lambda 事件函數支援的 HTTP API 端點所需的最低需求。此範例使用 AWS SAM 建立的預設 HTTP API。

YAML


AWSTemplateFormatVersion: '2010-09-09'
Description: AWS SAM template with a simple API definition
Resources:
  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: HttpApi
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
      Runtime: python3.7
Transform: AWS::Serverless-2016-10-31

具有 Auth 的 HttpApi

下列範例示範如何在 HTTP API 端點上設定授權。

YAML


Properties:
  FailOnWarnings: true
  Auth:
    DefaultAuthorizer: OAuth2
    Authorizers:
      OAuth2:
        AuthorizationScopes:
          - scope4
        JwtConfiguration:
          issuer: "https://www.example.com/v1/connect/oauth2"
          audience:
            - MyApi
        IdentitySource: "$request.querystring.param"

具有 OpenAPI 定義的 HttpApi

下列範例示範如何將 OpenAPI 定義新增至範本。

請注意，會為參考此 HTTP API 的 HttpApi 事件 AWS SAM 填入任何遺失的 Lambda 整合。 AWS SAM 也會新增 HttpApi 事件參考的任何遺失路徑。

YAML


Properties:
  FailOnWarnings: true
  DefinitionBody:
    info:
      version: '1.0'
      title:
        Ref: AWS::StackName
    paths:
      "/":
        get:
          security:
          - OpenIdAuth:
            - scope1
            - scope2
          responses: {}
    openapi: 3.0.1
    securitySchemes:
      OpenIdAuth:
        type: openIdConnect
        x-amazon-apigateway-authorizer:
          identitySource: "$request.querystring.param"
          type: jwt
          jwtConfiguration:
            audience:
            - MyApi
            issuer: https://www.example.com/v1/connect/oidc
          openIdConnectUrl: https://www.example.com/v1/connect/oidc/.well-known/openid-configuration

具有組態設定的 HttpApi

下列範例示範如何將 HTTP API 和階段組態新增至範本。

YAML


AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Parameters:
  StageName:
    Type: String
    Default: Prod
    
Resources:
  HttpApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      InlineCode: |
          def handler(event, context):
              import json
              return {
                  "statusCode": 200,
                  "body": json.dumps(event),
              }
      Handler: index.handler
      Runtime: python3.7
      Events:
        ExplicitApi: # warning: creates a public endpoint
          Type: HttpApi
          Properties:
            ApiId: !Ref HttpApi
            Method: GET
            Path: /path
            TimeoutInMillis: 15000
            PayloadFormatVersion: "2.0"
            RouteSettings:
              ThrottlingBurstLimit: 600

  HttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: !Ref StageName
      Tags:
        Tag: Value
      AccessLogSettings:
        DestinationArn: !GetAtt AccessLogs.Arn
        Format: $context.requestId
      DefaultRouteSettings:
        ThrottlingBurstLimit: 200
      RouteSettings:
        "GET /path":
          ThrottlingBurstLimit: 500 # overridden in HttpApi Event
      StageVariables:
        StageVar: Value
      FailOnWarnings: true

  AccessLogs:
    Type: AWS::Logs::LogGroup

Outputs:
  HttpApiUrl:
    Description: URL of your API endpoint
    Value:
      Fn::Sub: 'https://${HttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/${StageName}/'
  HttpApiId:
    Description: Api id of HttpApi
    Value:
      Ref: HttpApi

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

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

文件慣用形式

執行時期

HttpApiAuth