翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # AWS::Serverless::HttpApi REST API よりもレイテンシーとコストが低い RESTful API を作成できる Amazon API Gateway HTTP API を作成します。詳細については、*API Gateway デベロッパーガイド*の「[HTTP API の操作](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html)」を参照してください。 CloudFormation フックまたは IAM ポリシーを使用して、API Gateway リソースにアクセスを制御するオーソライザーがアタッチされていることを確認することをお勧めします。 CloudFormation フックの使用の詳細については、*CloudFormation CLI ユーザーガイド*の[「フックの登録](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html)」および[apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub リポジトリ」を参照してください。 IAM ポリシーの使用の詳細については、「*API ゲートウェイデベロッパーガイド*」の「[API ルートに認可を要求する](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization)」を参照してください。 **注記** にデプロイすると AWS CloudFormation、 は AWS SAM リソースを CloudFormation リソース AWS SAM に変換します。詳細については、「[の生成済み CloudFormation リソース AWS SAM](sam-specification-generated-resources.md)」を参照してください。 ## 構文 AWS Serverless Application Model (AWS SAM) テンプレートでこのエンティティを宣言するには、次の構文を使用します。 ### YAML ``` Type: AWS::Serverless::HttpApi Properties: [AccessLogSettings](#sam-httpapi-accesslogsettings): {{[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)}} [Auth](#sam-httpapi-auth): {{HttpApiAuth}} [CorsConfiguration](#sam-httpapi-corsconfiguration): {{String | HttpApiCorsConfiguration}} [DefaultRouteSettings](#sam-httpapi-defaultroutesettings): {{[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)}} [DefinitionBody](#sam-httpapi-definitionbody): {{JSON}} [DefinitionUri](#sam-httpapi-definitionuri): {{String | HttpApiDefinition}} [Description](#sam-httpapi-description): {{String}} [DisableExecuteApiEndpoint](#sam-httpapi-disableexecuteapiendpoint): {{Boolean}} [Domain](#sam-httpapi-domain): {{HttpApiDomainConfiguration}} [FailOnWarnings](#sam-httpapi-failonwarnings): {{Boolean}} Name: {{String}} PropagateTags: {{Boolean}} [RouteSettings](#sam-httpapi-routesettings): {{[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)}} [StageName](#sam-httpapi-stagename): {{String}} [StageVariables](#sam-httpapi-stagevariables): {{[Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)}} [Tags](#sam-httpapi-tags): {{Map}} ``` ## プロパティ `AccessLogSettings` ステージのアクセスロギングのための設定です。 *タイプ*: [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings) *必須:* いいえ *CloudFormation 互換性*: このプロパティは、 `AWS::ApiGatewayV2::Stage`リソースの `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)`プロパティに直接渡されます。 `Auth` API Gateway HTTP API へのアクセスを制御するための認可を設定します。 詳細については、*API Gateway デベロッパーガイド*の「[JWT オーソライザーを使用した HTTP API へのアクセスの制御](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html)」を参照してください。 *タイプ*: [HttpApiAuth](sam-property-httpapi-httpapiauth.md) *必須:* いいえ *CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のものはありません。 `CorsConfiguration` すべての API Gateway HTTP API のクロスオリジンリソース共有 (CORS) を管理します。文字列として許可するドメインを指定、または `HttpApiCorsConfiguration` オブジェクトを指定します。CORS では OpenAPI 定義を変更 AWS SAM する必要があるため、CORS は `DefinitionBody`プロパティが指定されている場合にのみ機能することに注意してください。 詳細については、*API Gateway デベロッパーガイド*の「[HTTP API の CORS の設定](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-cors.html)」を参照してください。 `CorsConfiguration` が OpenAPI 定義とプロパティレベルの両方で設定されている場合、 は両方の設定ソースをプロパティを優先して AWS SAM マージします。このプロパティが `true` に設定されている場合、すべてのオリジンが許可されます。 *タイプ*: 文字列 \| [HttpApiCorsConfiguration](sam-property-httpapi-httpapicorsconfiguration.md) *必須:* いいえ *CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のものはありません。 `DefaultRouteSettings` この HTTP API のデフォルトルート設定です。これらの設定は、特定のルートの `RouteSettings` プロパティによって上書きされる場合を除き、すべてのルートに適用されます。 *Type*: [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings) *必須:* いいえ *CloudFormation 互換性*: このプロパティは、 `AWS::ApiGatewayV2::Stage`リソースの `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)`プロパティに直接渡されます。 `DefinitionBody` HTTP API を説明する OpenAPI 定義です。`DefinitionUri` または を指定しない場合`DefinitionBody`、 はテンプレート設定に基づいて `DefinitionBody` AWS SAM を生成します。 *Type*: JSON *必須:* いいえ *CloudFormation 互換性*: このプロパティは、 `AWS::ApiGatewayV2::Api`リソースの `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)`プロパティに似ています。特定のプロパティが指定されている場合、渡される`DefinitionBody`前に にコンテンツを挿入したり、 を変更 AWS SAM したりできます CloudFormation。プロパティには `Auth`、および対応する `AWS::Serverless::Function` のための HttpApi タイプの `EventSource` が含まれます。 `DefinitionUri` HTTP API を定義する OpenAPI 定義の Amazon Simple Storage Service (Amazon S3) URI、ローカルファイルパス、またはロケーションオブジェクトです。このプロパティが参照する Amazon S3 オブジェクトは、有効な OpenAPI 定義ファイルである必要があります。を指定しない場合、`DefinitionUri`または が指定されている場合、 `DefinitionBody`はテンプレート設定に基づいて `DefinitionBody` AWS SAM を生成します。 ローカルファイルパスを指定する場合は、定義が適切に変換されるようにするために、テンプレートが `sam deploy` または `sam package` コマンドを含むワークフローを実行する必要があります。 `DefinitionUri` を使用して参照する外部 OpenApi 定義ファイルでは、組み込み関数はサポートされていません。OpenApi 定義をテンプレートにインポートするには、[Include transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html) が含まれる `DefinitionBody` プロパティを使用します。 *タイプ*: 文字列 \| [HttpApiDefinition](sam-property-httpapi-httpapidefinition.md) *必須:* いいえ *CloudFormation 互換性*: このプロパティは、 `AWS::ApiGatewayV2::Api`リソースの `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-bodys3location)`プロパティに似ています。ネストされた Amazon S3 プロパティには異なる名前が付けられています。 `Description` HTTP API リソースの説明です。 を指定すると`Description`、 AWS SAM は `description`フィールドを設定して HTTP API リソースの OpenApi 定義を変更します。次のシナリオではエラーが発生します。 + `DefinitionBody` プロパティは、Open API 定義で設定された `description` フィールドで指定されます。これにより、解決 AWS SAM されない `description`フィールドの競合が発生します。 + `DefinitionUri` プロパティが指定されています。Amazon AWS SAM S3 から取得される Open API 定義は変更されません。 Amazon S3 *タイプ*: 文字列 *必須:* いいえ *CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のものはありません。 `DisableExecuteApiEndpoint` クライアントがデフォルトの `execute-api` エンドポイント `https://{api_id}.execute-api.{region}.amazonaws.com` を使用して HTTP API を呼び出すことができるかどうかを指定します。デフォルトで、クライアントはデフォルトのエンドポイントを使用して API を呼び出すことができます。クライアントが API の呼び出しにカスタムドメイン名以外を使用しないようにするには、デフォルトのエンドポイントを無効にします。 このプロパティを使用するには、 `DefinitionBody` プロパティではなく `DefinitionUri`プロパティを指定するか、OpenAPI 定義の `x-amazon-apigateway-endpoint-configuration` を `disableExecuteApiEndpoint` に定義する必要があります。 型: ブール *必須:* いいえ *CloudFormation 互換性*: このプロパティは、 `AWS::ApiGatewayV2::Api`リソースの `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableexecuteapiendpoint)`プロパティに似ています。これは `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)` 拡張機能の `disableExecuteApiEndpoint` プロパティに直接渡され、`AWS::ApiGatewayV2::Api` リソースの ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)` プロパティに追加されます。 `Domain` この API Gateway HTTP API のカスタムドメインを設定します。 *タイプ*: [HttpApiDomainConfiguration](sam-property-httpapi-httpapidomainconfiguration.md) *必須:* いいえ *CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のものはありません。 `FailOnWarnings` 警告が発生したときに HTTP API の作成をロールバックするか (`true`) しないか (`false`) を指定します。デフォルト値は `false` です。 *タイプ*: ブール *必須:* いいえ *CloudFormation 互換性*: このプロパティは、 `AWS::ApiGatewayV2::Api`リソースの `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-failonwarnings)`プロパティに直接渡されます。 `Name` HTTP API リソースの名前。 を指定すると`Name`、 AWS SAM は `title`フィールドを設定して HTTP API リソースの OpenAPI 定義を変更します。次のシナリオではエラーが発生します。 + `DefinitionBody` プロパティは、Open API 定義で設定された `title` フィールドで指定されます。これにより、解決 AWS SAM されない `title`フィールドの競合が発生します。 + `DefinitionUri` プロパティが指定されています。Amazon AWS SAM S3 から取得される Open API 定義は変更されません。 Amazon S3 *タイプ*: 文字列 *必須:* いいえ *CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のプロパティはありません。 `PropagateTags` [AWS::Serverless::HttpApi](sam-specification-generated-resources-httpapi.md) が生成したリソースに `Tags` プロパティからのタグを渡すかどうかを指定します。`True` を指定して、生成されたリソースにタグを伝播します。 型: ブール *必須:* いいえ *デフォルト*: `False` *CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のものはありません。 `RouteSettings` この HTTP API に対するルートごとのルート設定です。詳細については、*API Gateway デベロッパーガイド*の「[HTTP API のルートの使用](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html)」を参照してください。 *Type*: [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings) *必須:* いいえ *CloudFormation 互換性*: このプロパティは、 `AWS::ApiGatewayV2::Stage`リソースの `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)`プロパティに直接渡されます。 `StageName` API ステージの名前です。名前が指定されていない場合、 は API Gateway の `$default`ステージ AWS SAM を使用します。 *タイプ*: 文字列 *必須:* いいえ *デフォルト*: $default *CloudFormation 互換性*: このプロパティは、 `AWS::ApiGatewayV2::Stage`リソースの `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagename)`プロパティに直接渡されます。 `StageVariables` ステージ変数を定義するマップです。変数名には、英数字とアンダースコアを使用できます。値は [A-Za-z0-9-.\_\~:/?\#&=,]\+ に一致する必要があります。 *タイプ*: [Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables) *必須:* いいえ *CloudFormation 互換性*: このプロパティは、 `AWS::ApiGatewayV2::Stage`リソースの `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)`プロパティに直接渡されます。 `Tags` この API Gateway ステージに追加するタグを指定するマップ (文字列対文字列) です。キーの長さは 1～128 文字の Unicode 文字で、プレフィックス `aws:` を含めることはできません。以下の文字を使用できます。一連の Unicode 文字、数字、空白、`_`、`.`、`/`、`=`、`+`、`-`。値は 1～256 文字の Unicode 文字にすることができます。 *タイプ*: マップ *必須:* いいえ *CloudFormation 互換性*: このプロパティは に固有 AWS SAM であり、 CloudFormation 同等のプロパティはありません。 *追加の注意*: `Tags`プロパティは OpenAPI 定義を変更する必要がある AWS SAM ため、タグは `DefinitionBody`プロパティが指定されている場合のみ追加されます。 `DefinitionUri` プロパティが指定されている場合、タグは追加されません。 は`httpapi:createdBy:SAM`タグ AWS SAM を自動的に追加します。タグは、`AWS::ApiGatewayV2::Stage` リソースと `AWS::ApiGatewayV2::DomainName` リソース (`DomainName` が指定されている場合) にも追加されます。 ## 戻り値 ### 参照番号 このリソースの論理 ID を `Ref` 組み込み関数に渡すと、`Ref` は基盤となる `AWS::ApiGatewayV2::Api` リソースの API ID (`a1bcdef2gh` など) を返します。 `Ref` 関数の使用方法の詳細については、*AWS CloudFormation ユーザーガイド*の「[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html)」を参照してください。 ## 例 ### シンプルな 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 を使用した HTTP API 以下の例は、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 イベントの欠落している Lambda 統合 AWS SAM をすべて埋めることに注意してください。 は、HttpApi イベントが参照する欠落しているパス AWS SAM も追加します。 #### 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 ```