構文プロパティ戻り値例

AWS::Serverless::HttpApi

REST API よりもレイテンシーとコストが低い RESTful API を作成できる Amazon API Gateway HTTP API を作成します。詳細については、API Gateway デベロッパーガイドの「HTTP API の操作」を参照してください。

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

CloudFormation フックの使用の詳細については、「CloudFormation CLI ユーザーガイド」の「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::HttpApi
Properties:
  AccessLogSettings: AccessLogSettings
  Auth: HttpApiAuth
  CorsConfiguration: String | HttpApiCorsConfiguration
  DefaultRouteSettings: RouteSettings
  DefinitionBody: JSON
  DefinitionUri: String | HttpApiDefinition
  Description: String
  DisableExecuteApiEndpoint: Boolean
  Domain: HttpApiDomainConfiguration
  FailOnWarnings: Boolean
  Name: String
  PropagateTags: Boolean
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

プロパティ

AccessLogSettings

ステージのアクセスロギングのための設定です。

タイプ: AccessLogSettings

必須: いいえ

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

Auth

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

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

タイプ: HttpApiAuth

必須: いいえ

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

CorsConfiguration

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

詳細については、API Gateway デベロッパーガイドの「HTTP API の CORS の設定」を参照してください。

注記

OpenAPI 定義内とプロパティレベルの両方で CorsConfiguration が設定されている場合、AWS SAM は両方の設定ソースを統合し、プロパティが優先されます。このプロパティが true に設定されている場合、すべてのオリジンが許可されます。

タイプ: 文字列 | HttpApiCorsConfiguration

必須: いいえ

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

DefaultRouteSettings

この HTTP API のデフォルトルート設定です。これらの設定は、特定のルートの RouteSettings プロパティによって上書きされる場合を除き、すべてのルートに適用されます。

Type: RouteSettings

必須: いいえ

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

DefinitionBody

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

Type: JSON

必須: いいえ

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

DefinitionUri

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

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

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

タイプ: 文字列 | HttpApiDefinition

必須: いいえ

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

Description

HTTP API リソースの説明です。

Description を指定すると、AWS SAM は description フィールドを設定して HTTP API リソースの OpenAPI 定義を変更します。次のシナリオではエラーが発生します。

DefinitionBody プロパティが Open API 定義で設定された description フィールドで指定されている – これは AWS SAM で解決されない description フィールドの競合を引き起こします。
DefinitionUri プロパティが指定されている – AWS SAM は Amazon S3 から取得された Open API 定義を変更しません。

タイプ: 文字列

必須: いいえ

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 プロパティに似ています。これは x-amazon-apigateway-endpoint-configuration 拡張機能の disableExecuteApiEndpoint プロパティに直接渡され、AWS::ApiGatewayV2::Api リソースの Body プロパティに追加されます。

Domain

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

タイプ: HttpApiDomainConfiguration

必須: いいえ

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

FailOnWarnings

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

タイプ: ブール

必須: いいえ

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

Name

HTTP API リソースの名前。

Name を指定すると、AWS SAM は title フィールドを設定して HTTP API リソースの OpenAPI 定義を変更します。次のシナリオではエラーが発生します。

DefinitionBody プロパティが Open API 定義で設定された title フィールドで指定されている – これは AWS SAM で解決されない title フィールドの競合を引き起こします。
DefinitionUri プロパティが指定されている – AWS SAM は Amazon S3 から取得された Open API 定義を変更しません。

タイプ: 文字列

必須: いいえ

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

PropagateTags

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

タイプ: ブール

必須: いいえ

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

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

RouteSettings

この HTTP API に対するルートごとのルート設定です。詳細については、API Gateway デベロッパーガイドの「HTTP API のルートの使用」を参照してください。

Type: RouteSettings

必須: いいえ

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

StageName

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

型: 文字列

必須: いいえ

デフォルト: $default

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

StageVariables

ステージ変数を定義するマップです。変数名には、英数字とアンダースコアを使用できます。値は [A-Za-z0-9-._~:/?#&=,]+ に一致する必要があります。

タイプ: Json

必須: いいえ

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

Tags

この API Gateway ステージに追加するタグを指定するマップ (文字列対文字列) です。キーの長さは 1～128 文字の Unicode 文字で、プレフィックス aws: を含めることはできません。以下の文字を使用できます。一連の Unicode 文字、数字、空白、_、.、/、=、+、-。値は 1～256 文字の Unicode 文字にすることができます。

タイプ: マップ

必須: いいえ

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

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

戻り値

参照番号

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

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

例

シンプルな 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 定義を追加する方法を示しています。

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

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

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

ドキュメントの表記規則

ランタイム

HttpApiAuth