AWS::Serverless::Api

HTTPS エンドポイント経由で呼び出すことができる Amazon API Gateway リソースとメソッドのコレクションを作成します。

AWS::Serverless::Api リソースを AWS サーバーレスアプリケーション定義テンプレートに明示的に追加する必要はありません。このタイプのリソースは、AWS::Serverless::Function リソースを参照しないテンプレートで定義された AWS::Serverless::Api リソースに定義される Api イベントの和集合から暗黙的に作成されます。

AWS::Serverless::Api リソースは、OpenApi を使用して API を定義および文書化するために使用する必要があります。これは、基盤となる Amazon API Gateway リソースを設定する機能をより多く提供します。

API Gateway リソースへのアクセスを制御するオーソライザーがアタッチされていることを確認するため、CloudFormation フックまたは IAM ポリシーを使用することをお勧めします。

CloudFormation フックの使用の詳細については、「CloudFormation CLI user guide」の「Registering hooks」、および GitHub リポジトリの「apigw-enforce-authorizer」を参照してください。

IAM ポリシーの使用の詳細については、「API ゲートウェイデベロッパーガイド」の「API ルートに認可を要求する」を参照してください。

注記

AWS CloudFormation にデプロイすると、AWS SAM は、AWS SAM リソースを CloudFormation リソースに変換します。詳細については、「AWS SAM 向けに生成された CloudFormation リソース」を参照してください。

構文

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
  Policy: JSON
  StageName: String
  Tags: Map
  TracingEnabled: Boolean
  Variables: Map

プロパティ

AccessLogSetting

ステージのアクセスログ設定を行います。

タイプ: AccessLogSetting

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::Stage リソースの AccessLogSetting プロパティに直接渡されます。

AlwaysDeploy

API への変更が検出されない場合でも、常に API をデプロイします。

タイプ: ブール

必須: いいえ

CloudFormation との互換性: このプロパティは AWS SAM に固有であり、CloudFormation に同等のものはありません。

ApiKeySourceType

使用量プランに沿ってリクエストを計測するための API キーのソース。有効な値は、HEADER および AUTHORIZER です。

タイプ: 文字列

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの ApiKeySourceType プロパティに直接渡されます。

Auth

API Gateway API へのアクセスを制御するための認可を設定します。

AWS SAM を使用したアクセス権の設定に関する詳細については、「AWS SAM テンプレートを使用して API アクセスを制御する」を参照してください。グローバルオーソライザーを上書きする方法の例については、「Amazon API Gateway REST API のグローバルオーソライザーをオーバーライドする」を参照してください。

タイプ: ApiAuth

必須: いいえ

CloudFormation との互換性: このプロパティは AWS SAM に固有であり、CloudFormation に同等のものはありません。

BinaryMediaTypes

API が返すことができる MIME タイプのリストです。これは、API のバイナリサポートを有効化するために使用します。

タイプ: リスト

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの BinaryMediaTypes プロパティに似ています。BinaryMediaTypes のリストは、CloudFormation リソースと OpenAPI ドキュメントの両方に追加されます。

CacheClusterEnabled

ステージでキャッシュが有効化されているかどうかを示します。レスポンスをキャッシュするには、MethodSettings で CachingEnabled を true に設定することも必要です。

タイプ: ブール

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::Stage リソースの CacheClusterEnabled プロパティに直接渡されます。

CacheClusterSize

ステージのキャッシュクラスターサイズです。

型: 文字列

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::Stage リソースの CacheClusterSize プロパティに直接渡されます。

CanarySetting

通常のデプロイの段階に Canary 設定を設定します。

タイプ: CanarySetting

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::Stage リソースの CanarySetting プロパティに直接渡されます。

Cors

すべての API Gateway API のクロスオリジンリソース共有 (CORS) を管理します。許可するドメインを文字列として指定するか、追加の CORS 設定でディクショナリを指定します。

注記

CORS では、OpenAPI 定義の変更に AWS SAM が必要です。CORS を有効にするには、DefinitionBody の中でインライン OpenAPI 定義を作成します。

CORS の詳細については、Amazon API Gateway デベロッパーガイドの「REST API リソースの CORS を有効にする」を参照してください。

タイプ: 文字列 | CorsConfiguration

必須: いいえ

CloudFormation との互換性: このプロパティは AWS SAM に固有であり、CloudFormation に同等のものはありません。

DefinitionBody

API を説明する OpenAPI 仕様です。DefinitionUri と DefinitionBody のどちらも指定されていない場合、SAM はテンプレート設定に基づいて DefinitionBody を生成します。

API を定義するローカルの OpenAPI ファイルを参照するには、AWS::Include 変換を使用してください。詳細についてはAWS SAM でローカルファイルをアップロードする方法を参照してください。

Type: JSON

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの Body プロパティに似ています。特定のプロパティが提供されている場合、コンテンツは、CloudFormation に渡される前に DefinitionBody に挿入または変更される可能性があります。プロパティには Auth、BinaryMediaTypes、Cors、GatewayResponses、Models、および、対応する AWS::Serverless::Function 向けの EventSource タイプの API が含まれます。

DefinitionUri

Amazon S3 URI、ローカルファイルパス、または API を定義する OpenAPI ドキュメントのロケーションオブジェクトです。このプロパティが参照する Amazon S3 オブジェクトは、有効な OpenAPI ファイルである必要があります。DefinitionUri と DefinitionBody のどちらも指定されていない場合、SAM はテンプレート設定に基づいて DefinitionBody を生成します。

ローカルファイルパスを指定する場合は、定義が適切に変換されるようにするために、テンプレートが sam deploy または sam package コマンドを含むワークフローを実行する必要があります。

組み込み関数は、DefinitionUri で参照される外部 OpenApi ファイルではサポートされていません。その代わりに、Include Transform で DefinitionBody プロパティを使用して、OpenApi 定義をテンプレートにインポートします。

タイプ: 文字列 | ApiDefinition

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの BodyS3Location プロパティに似ています。ネストされた Amazon S3 プロパティには異なる名前が付けられています。

Description

API リソースの説明です。

型: 文字列

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの Description プロパティに直接渡されます。

DisableExecuteApiEndpoint

クライアントがデフォルトの execute-api エンドポイントを使用して API を呼び出すことができるかどうかを指定します。デフォルトでは、クライアントはデフォルトの https://{api_id}.execute-api.{region}.amazonaws.com を使用して API を呼び出すことができます。クライアントがカスタムドメイン名を使用して API を呼び出すように要求するには、True を指定します。

タイプ: ブール

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの DisableExecuteApiEndpoint プロパティに似ています。これは x-amazon-apigateway-endpoint-configuration 拡張機能の disableExecuteApiEndpoint プロパティに直接渡され、AWS::ApiGateway::RestApi リソースの Body プロパティに追加されます。

Domain

この API Gateway API のカスタムドメインを設定します。

タイプ: DomainConfiguration

必須: いいえ

CloudFormation との互換性: このプロパティは AWS SAM に固有であり、CloudFormation に同等のものはありません。

EndpointConfiguration

REST API のエンドポイントタイプです。

タイプ: EndpointConfiguration

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの EndpointConfiguration プロパティに似ています。ネストされた設定プロパティには異なる名前が付けられています。

FailOnWarnings

警告が発生したときに、API 作成をロールバックするか (true)、しないか (false) を指定します。デフォルト値は false です。

タイプ: ブール

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの FailOnWarnings プロパティに直接渡されます。

GatewayResponses

API のゲートウェイレスポンスを設定します。ゲートウェイレスポンスは、直接、または Lambda オーソライザーを使用して返される API Gateway からのレスポンスです。詳細については、ゲートウェイレスポンス用の API Gateway OpenApi 拡張機能に関するドキュメントを参照してください。

タイプ: マップ

必須: いいえ

CloudFormation との互換性: このプロパティは AWS SAM に固有であり、CloudFormation に同等のものはありません。

MergeDefinitions

AWS SAM は API イベントソースから OpenAPI の仕様を生成します。AWS SAM が AWS::Serverless::Api リソースで定義されたインライン OpenAPI 仕様にこれをマージするようにするには true を指定します。マージしない場合は false を指定します。

MergeDefinitions では、AWS::Serverless::Api の DefinitionBody プロパティを定義する必要があります。MergeDefinitions は AWS::Serverless::Api の DefinitionUri プロパティと互換性がありません。

デフォルト値: false

タイプ: ブール

必須: いいえ

CloudFormation との互換性: このプロパティは AWS SAM に固有であり、CloudFormation に同等のものはありません。

MethodSettings

ロギング、メトリクス、CacheTTL、スロットリングなどの API ステージのすべての設定を行います。

タイプ: MethodSetting のリスト

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::Stage リソースの MethodSettings プロパティに直接渡されます。

MinimumCompressionSize

クライアントの Accept-Encoding ヘッダーに基づくレスポンス本文の圧縮を許可します。圧縮は、レスポンス本文のサイズが設定したしきい値以上の場合にトリガーされます。本文サイズの最大しきい値は 10 MB (10,485,760 バイト) です。gzip、deflate、および identity の圧縮タイプがサポートされます。

タイプ: 整数

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの MinimumCompressionSize プロパティに直接渡されます。

Mode

このプロパティは、OpenAPI を使用して REST API を定義するときにのみ適用されます。Mode は、API Gateway がリソース更新を処理する方法を決定します。詳細については、AWS::ApiGateway::RestApi リソースタイプのModeプロパティを参照してください。

有効な値: overwrite または merge

型: 文字列

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの Mode プロパティに直接渡されます。

Models

API メソッドで使用されるスキーマです。これらのスキーマは、JSON または YAML を使用して記述できます。サンプルモデルについては、このページの下部にある「例」セクションを参照してください。

タイプ: マップ

必須: いいえ

CloudFormation との互換性: このプロパティは AWS SAM に固有であり、CloudFormation に同等のものはありません。

Name

API Gateway RestApi リソースの名前です。

型: 文字列

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの Name プロパティに直接渡されます。

OpenApiVersion

使用する OpenApi のバージョンです。これは、Swagger 仕様の 2.0、または 3.0.1 のような OpenApi 3.0 バージョンの 1 つにすることができます。OpenAPI の詳細については、「OpenAPI Specification」を参照してください。

注記

AWS SAM は、Stage と呼ばれるステージをデフォルトで作成します。このプロパティに有効な値を設定すると、ステージ Stage が作成されなくなります。

タイプ: 文字列

必須: いいえ

CloudFormation との互換性: このプロパティは AWS SAM に固有であり、CloudFormation に同等のものはありません。

PropagateTags

AWS::Serverless::Api が生成したリソースに Tags プロパティからのタグを渡すかどうかを指定します。True を指定して、生成されたリソースにタグを伝播します。

タイプ: ブール

必須: いいえ

[Default] (デフォルト): False

CloudFormation との互換性: このプロパティは AWS SAM に固有であり、CloudFormation に同等のものはありません。

Policy

API の許可が含まれるポリシードキュメント。ポリシーの ARN を設定するには、区切り記号および !Join と "" の値として、"execute-api:/" と "*" 組み込み関数を使用します。

Type: JSON

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::RestApi リソースの Policy プロパティに直接渡されます。

StageName

API Gateway が invoke Uniform Resource Identifier (URI) の最初のパスセグメントとして使用するステージの名前です。

ステージリソースを参照するには、<api-logical-id>.Stage を使用します。AWS::Serverless::Api リソースの指定時に生成されるリソースの参照に関する詳細については、「AWS::Serverless::Api が指定された場合、生成される CloudFormation リソース」を参照してください。生成された CloudFormation リソースの一般情報については、「AWS SAM 向けに生成された CloudFormation リソース」を参照してください。

型: 文字列

必須: はい

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::Stage リソースの StageName プロパティに似ています。SAM では必須ですが、API Gateway では必須ではありません。

その他の注意点: 暗黙的な API には「prod」という名前のステージがあります。

Tags

この API Gateway ステージに追加されるタグを指定するマップ (文字列対文字列) です。タグの有効なキーと値の詳細については、AWS CloudFormation ユーザーガイドのリソースタグを参照してください。

タイプ: マップ

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::Stage リソースの Tags プロパティに似ています。SAM の Tags プロパティは、キーバリューペアで構成されています。CloudFormation では、タグオブジェクトのリストで構成されています。

TracingEnabled

このステージに X-Ray を使用したアクティブトレーシングが有効化されているかどうかを示します。X-Ray の詳細については、API Gateway デベロッパーガイドの「X-Ray を使用した REST API へのユーザーリクエストのトレース」を参照してください。

タイプ: ブール

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::Stage リソースの TracingEnabled プロパティに直接渡されます。

Variables

ステージ変数を定義するマップ (文字列対文字列) で、変数名はキー、変数値は値です。変数名に使用できるのは英数字のみです。値は次の正規表現に一致する必要があります: [A-Za-z0-9._~:/?#&=,-]+。

タイプ: マップ

必須: いいえ

CloudFormation との互換性: このプロパティは、AWS::ApiGateway::Stage リソースの Variables プロパティに直接渡されます。

戻り値

参照番号

このリソースの論理 ID が Ref 組み込み関数に提供されると、基盤となる API Gateway API の ID が返されます。

Ref 関数の使用方法の詳細については、AWS CloudFormation ユーザーガイドの「Ref」を参照してください。

Fn::GetAtt

Fn::GetAtt は、このタイプの指定された属性の値を返します。利用可能な属性とサンプル戻り値は以下のとおりです。

Fn::GetAtt の使用の詳細については、AWS CloudFormation ユーザーガイドの「Fn::GetAtt」を参照してください。

RootResourceId

RestApi リソースのルートソース ID (a0bc123d4e など) です。

例

SimpleApiExample

API エンドポイントを持つ Lambda 関数が含まれた Hello World 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

Lambda 統合および CORS 設定と共に、外部 Swagger ファイルに定義された API が含まれる AWS SAM テンプレートのスニペットです。これは、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

Amazon Cognito を使用して API に対するリクエストを承認する API を使用する AWS SAM テンプレートのスニペットです。これは、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

Models スキーマが含まれた API を使用する AWS SAM テンプレートのスニペットです。これは、2 つのモデルスキーマを持つ AWS::Serverless::Api 定義を示す AWS SAM テンプレートファイルの一部分です。

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 関数が含まれた Hello World AWS SAM テンプレートです。API では、1 つのリソースとメソッドに対してキャッシュが有効になっています。キャッシュの詳細については、「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}

プライベート API を使用したカスタムドメインの例

プライベートドメインにマップされた API エンドポイントを持つ Lambda 関数が含まれた Hello World AWS SAM テンプレートです。テンプレートはVPC エンドポイントとプライベートドメインの間にドメイン名アクセスの関連付けを作成します。詳細については、「API Gateway でのプライベート API のカスタムドメイン名」を参照してください。

YAML

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template configured with a custom domain using a private API

Parameters:
    DomainName:
      Type: String
      Default: mydomain.example.com
    CertificateArn:
      Type: String
    HostedZoneId:
      Type: String
    VpcEndpointId:
      Type: String
    VpcEndpointDomainName:
      Type: String
    VpcEndpointHostedZoneId:
      Type: String

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
      Handler: index.handler
      Runtime: python3.13
      Events:
        Fetch:
          Type: Api
          Properties:
            RestApiId:
              Ref: MyApi
            Method: Get
            Path: /get
  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      EndpointConfiguration:
        Type: PRIVATE
        VPCEndpointIds:
        - !Ref VpcEndpointId
      Policy:
        Version: '2012-10-17		 	 	 '
        Statement:
        - Effect: Allow
          Principal: '*'
          Action: execute-api:Invoke
          Resource: execute-api:/*
        - Effect: Deny
          Principal: '*'
          Action: execute-api:Invoke
          Resource: execute-api:/*
          Condition:
            StringNotEquals:
              aws:SourceVpce: !Ref VpcEndpointId
      Domain:
        DomainName: !Ref DomainName
        CertificateArn: !Ref CertificateArn
        EndpointConfiguration: PRIVATE
        BasePath:
        - /
        Route53:
          HostedZoneId: !Ref HostedZoneId
          VpcEndpointDomainName: !Ref VpcEndpointDomainName
          VpcEndpointHostedZoneId: !Ref VpcEndpointHostedZoneId
        AccessAssociation:
          VpcEndpointId: !Ref VpcEndpointId
        Policy:
          Version: '2012-10-17		 	 	 '
          Statement:
          - Effect: Allow
            Principal: '*'
            Action: execute-api:Invoke
            Resource: execute-api:/*
          - Effect: Deny
            Principal: '*'
            Action: execute-api:Invoke
            Resource: execute-api:/*
            Condition:
              StringNotEquals:
                aws:SourceVpce: !Ref VpcEndpointId