AWS::Serverless::HttpApi - AWS Serverless Application Model

「翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。」

AWS::Serverless::HttpApi

Amazon API Gateway HTTP API を作成します。これにより、REST よりも低レイテンシーで低コストRESTfulAPIsで を作成できますAPIs。 詳細については、の「HTTP の使用」を参照してくださいAPIsAPI Gateway 開発者ガイド

構文

でこのエンティティを宣言するには AWS サーバーレスアプリケーションモデル (AWS SAM) テンプレート。次の構文を使用します。

プロパティ

AccessLogSettings

ステージのアクセスログ記録の設定。

タイプ: AccessLogSettings

必須: いいえ

AWS CloudFormation compatibility: このプロパティは、 AccessLogSettings リソースの AWS::ApiGatewayV2::Stage プロパティに直接渡されます。

Auth

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

詳細については、の「JWT オーソAPIsライザーを使用した HTTP へのアクセスの制御」を参照してくださいAPI Gateway 開発者ガイド

タイプ: HttpApiAuth

必須: いいえ

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

CorsConfiguration

すべての API Gateway HTTP の Cross-Origin Resource Sharing (CORS) を管理しますAPIs。 許可するドメインを文字列として指定するか、 HttpApiCorsConfiguration オブジェクトを指定します。CORS では AWS SAM でOpenAPI定義を変更する必要があるため、CORS は DefinitionBody プロパティが指定されている場合にのみ機能することに注意してください。

詳細については、の「HTTP API の CORS の設定」を参照してくださいAPI Gateway 開発者ガイド

注意: が CorsConfiguration 定義とプロパティレベルの両方で設定されている場合、 OpenAPI は両方の設定ソースをプロパティに優先してAWS SAMマージします。

注意: このプロパティを に設定するとtrue、すべてのオリジンが許可されます。

タイプ: 文字列 | HttpApiCorsConfiguration

必須: いいえ

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

DefaultRouteSettings

この HTTP API のデフォルトのルート設定。これらの設定は、特定のルートの RouteSettings プロパティによって上書きされない限り、すべてのルートに適用されます。

タイプ: RouteSettings

必須: いいえ

AWS CloudFormation compatibility: このプロパティは、 RouteSettings リソースの AWS::ApiGatewayV2::Stage プロパティに直接渡されます。

DefinitionBody

HTTP API を記述するOpenAPI定義。DefinitionUri または を指定しない場合DefinitionBody、 はテンプレート設定に基づいて AWS SAM DefinitionBody を生成します。

タイプ: 文字列

必須: いいえ

AWS CloudFormation compatibility: このプロパティは、 Body リソースの AWS::ApiGatewayV2::Api プロパティに似ています。特定のプロパティが指定されている場合、 は にコンテンツを挿入したり、 に渡AWS SAMされる前に を変更したりDefinitionBodyすることがありますAWS CloudFormation。プロパティには、対応するAuthリソースの EventSource および HttpApi AWS::Serverless::Function タイプの が含まれます。

DefinitionUri

HTTP API を定義するAmazon Simple Storage Service定義の Amazon S3 (OpenAPI) URI、ローカルファイルパス、または場所オブジェクト。このプロパティが参照する Amazon S3 オブジェクトは、有効なOpenAPI定義ファイルである必要があります。を指定しない場合DefinitionUri、または を指定しない場合、 DefinitionBody はテンプレート設定AWS SAMに基づいて DefinitionBody を生成します。

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

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

タイプ: 文字列 | HttpApiDefinition

必須: いいえ

AWS CloudFormation compatibility: このプロパティは、 BodyS3Location リソースの AWS::ApiGatewayV2::Api プロパティに似ています。ネストされた Amazon S3 プロパティの名前は異なります。

Description

HttpApi リソースの説明。

注意: このプロパティでは、 AWS SAM HttpApi でOpenAPIリソースdescriptionの定義を変更して フィールドを設定する必要があります。次の 2 つのシナリオではエラーになります。1) DefinitionBody プロパティはdescription、 定義の OpenAPI フィールドで指定されます (これが解決AWS SAMされない競合であるため)。2) DefinitionUri プロパティは指定されます ( は から取得したAWS SAM定義を変更OpenAPIしないためAmazon S3)。

タイプ: 文字列

必須: いいえ

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

DisableExecuteApiEndpoint

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

タイプ: ブール値

必須: いいえ

AWS CloudFormation compatibility: このプロパティは、 DisableExecuteApiEndpoint リソースの AWS::ApiGatewayV2::Api プロパティに直接渡されます。

Domain

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

タイプ: HttpApiDomainConfiguration

必須: いいえ

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

FailOnWarnings

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

タイプ: ブール値

必須: いいえ

AWS CloudFormation compatibility: このプロパティは、 FailOnWarnings リソースの AWS::ApiGatewayV2::Api プロパティに直接渡されます。

RouteSettings

この HTTP API のルート設定 (ルートごと)。詳細については、『』の「HTTP のルートの使用」を参照してくださいAPIsAPI Gateway 開発者ガイド

タイプ: RouteSettings

必須: いいえ

AWS CloudFormation compatibility: このプロパティは、 RouteSettings リソースの AWS::ApiGatewayV2::Stage プロパティに直接渡されます。

StageName

API ステージの名前。名前を指定しない場合、 は の AWS SAM ステージ$defaultを使用しますAPI Gateway。

タイプ: 文字列

必須: いいえ

デフォルト: $default

AWS CloudFormation compatibility: このプロパティは、 StageName リソースの AWS::ApiGatewayV2::Stage プロパティに直接渡されます。

StageVariables

ステージ変数を定義するマップ。変数名には、英数字とアンダースコア文字を使用できます。値は [A-Za-z0-9 と一致する必要があります。

タイプ: Json

必須: いいえ

AWS CloudFormation compatibility: このプロパティは、 StageVariables リソースの AWS::ApiGatewayV2::Stage プロパティに直接渡されます。

Tags

このAPI Gatewayステージに追加するタグを指定するマップ (文字列から文字列)。キーと値に使用できるのは英数字のみです。キーの長さは 1~127 文字の Unicode 文字です。プレフィックス を含めることはできませんaws:。 値の長さは 1~255 文字の Unicode 文字です。

タイプ: マップ

必須: いいえ

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

追加メモ: Tags プロパティでは、 AWS SAM でOpenAPI定義を変更する必要があるため、タグは、 DefinitionBody プロパティが指定された—場合にのみ追加されます プロパティが指定された場合にのみ追加されます DefinitionUri プロパティが指定された場合にタグは追加されません。 は自動的に AWS SAM タグhttpapi:createdBy:SAMを追加します。タグは、 AWS::ApiGatewayV2::Stage リソースおよび AWS::ApiGatewayV2::DomainName リソース ( が指定されている場合) にも追加DomainNameされます。

戻り値

Ref

このリソースの論理 ID を組み込み Ref 関数に渡すと、 は基になるRefリソースの API ID ( など) AWS::ApiGatewayV2::Api を返しますa1bcdef2gh

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

シンプル 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

HttpApi と Auth

次の例は、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" OpenIdAuth: AuthorizationScopes: - scope1 - scope2 OpenIdConnectUrl: "https://www.example.com/v1/connect/oidc/.well-known/openid-configuration" JwtConfiguration: issuer: "https://www.example.com/v1/connect/oidc" audience: - MyApi IdentitySource: "$request.querystring.param"

HttpApi OpenAPI定義を使用した

次の例は、テンプレートに OpenAPI 定義を追加する方法を示しています。

は、この HTTP API を参照するAWS SAMイベントの不足しているLambda統合HttpApiを埋めることに注意してください。 は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