AWS::Serverless::Api - AWS Serverless Application Model

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

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

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

構文

AWS Serverless Application Model (AWS SAM) テンプレートでこのエンティティを宣言するには、以下の構文を使用します。

[Properties] (プロパティ)

AccessLogSetting

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

タイプ: AccessLogSetting

必須: いいえ

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

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

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

タイプ: ブール

必須: いいえ

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 では、OpenAPI 定義の変更に AWS SAM が必要です。このため、これが機能するのは DefinitionBody で Inline OpenApi が定義されている場合のみです。

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

タイプ: 文字列 | CorsConfiguration

必須: いいえ

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

DefinitionBody

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

Type: JSON

必須: いいえ

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

DefinitionUri

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

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

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

タイプ: 文字列 | ApiDefinition

必須: いいえ

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

Description

API リソースの説明です。

タイプ:文字列

必須: いいえ

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

DisableExecuteApiEndpoint

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

タイプ: ブール

必須: いいえ

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

Domain

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

タイプ: DomainConfiguration

必須: いいえ

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

EndpointConfiguration

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

タイプ: EndpointConfiguration

必須: いいえ

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

FailOnWarnings

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

タイプ: ブール

必須: いいえ

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

GatewayResponses

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

タイプ: マップ

必須: いいえ

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

MethodSettings

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

タイプ: MethodSettings

必須: いいえ

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、または 3.0.1 のような OpenApi 3.0 バージョンの 1 つにすることができます。OpenAPI の詳細については、「OpenAPI Specification」を参照してください。

注意: このプロパティに有効な値を設定すると、SAM が作成する Stage ステージも削除されます。

タイプ:文字列

必須: いいえ

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

StageName

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

ステージリソースを参照するには、<api-logical-id>.Stage を使用します。AWS::Serverless::Api リソースの指定時に生成されるリソースの参照に関する詳細については、「AWS CloudFormationAWS::Serverless::Api が指定されている時に生成された リソース」を参照してください。生成された 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 では、タグオブジェクトのリストで構成されています。

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 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

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 Resources: ApiGatewayApi: Type: AWS::Serverless::Api Properties: StageName: prod CacheClusterEnabled: true CacheClusterSize: '0.5' MethodSettings: - ResourcePath: / HttpMethod: GET CachingEnabled: true CacheTtlInSeconds: 300 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}