AWS::Serverless::Api

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

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

AWS::Serverless::Api リソースは、基盤となる Amazon API Gateway リソースを設定する機能を強化する OpenApiを使用して API を定義および文書化するために使用します。

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

AWS CloudFormation フックの使用の詳細については、 AWS CloudFormation CLI ユーザーガイドの「フックの登録」および apigw-enforce-authorizer GitHub リポジトリを参照してください。

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

注記

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

Syntax

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 「」を参照してくださいAPI Gateway 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

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

と入力します。 CanarySetting

必須: いいえ

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

Cors

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

注記

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

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

タイプ: 文字列 | CorsConfiguration

必須: いいえ

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

DefinitionBody

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

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

Type: JSON

必須: いいえ

AWS CloudFormation との互換性: このプロパティは、 AWS::ApiGateway::RestApiリソースの Bodyプロパティに似ています。特定のプロパティが指定されている場合、に渡されるDefinitionBody 前にコンテンツがに挿入されたり変更されたりすることがあります CloudFormation。プロパティには 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 コマンドを含むワークフローを実行する必要があります。

組み込み関数は、によって参照される外部 OpenApi ファイルではサポートされていませんDefinitionUri。代わりに、Include Transform で 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

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

タイプ: ブール

必須: いいえ

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

GatewayResponses

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

タイプ: マップ

必須: いいえ

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

MergeDefinitions

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

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

デフォルト値: false

タイプ: ブール

必須: いいえ

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

MethodSettings

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

タイプ: MethodSetting のリスト

必須: いいえ

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

MinimumCompressionSize

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

タイプ: 整数

必須: いいえ

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

Mode

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

有効な値: 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 Specification」を参照してください。

注記

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

タイプ: 文字列

必須: いいえ

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

PropagateTags

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

タイプ: ブール

必須: いいえ

デフォルト: False

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

StageName

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

ステージリソースを参照するには、<api-logical-id>.Stage を使用します。AWS::Serverless::Api リソースの指定時に生成されるリソースの参照に関する詳細については、「 AWS::Serverless::Api が指定された場合、生成される AWS CloudFormation リソース」を参照してください。生成された AWS CloudFormation リソースの一般的な情報については、「」を参照してください生成された 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 の Tags プロパティはキーと値のペアで構成され CloudFormation 、その中のは Tag オブジェクトのリストで構成されます。

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プロパティに直接渡されます。

戻り値

参照番号

このリソースの論理 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 テンプレートスニペット。これは AWS SAM テンプレートファイルの一部にすぎず、2 つのモデルスキーマを持つ 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 関数を含む 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}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

リソースとプロパティのリファレンス

ApiAuth