AWS::Serverless::WebSocketApi

Amazon API Gateway WebSocket API を作成します。これにより、双方向のインタラクティブ通信アプリケーションを作成できます。WebSocket APIsを使用すると、サーバーはクライアントにメッセージをリクエストすることなくメッセージを送信できます。詳細については、APIsWebSocket API の使用」を参照してください。

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

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

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

注記

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

構文

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

YAML


Type: AWS::Serverless::WebSocketApi
Properties:
  ApiKeySelectionExpression: String
  AccessLogSettings: AccessLogSettings
  Auth: WebSocketApiAuth
  DefaultRouteSettings: RouteSettings
  Description: String
  DisableExecuteApiEndpoint: Boolean
  DisableSchemaValidation: Boolean
  Domain: WebSocketApiDomainConfiguration
  IpAddressType: String
  Name: String
  PropagateTags: Boolean
  Routes: RouteConfiguration
  RouteSelectionExpression: String
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

プロパティ

ApiKeySelectionExpression

API キー選択表現。詳細については、「 API Gateway デベロッパーガイド」の「API キー選択式」を参照してください。

タイプ: 文字列

必須: いいえ

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

AccessLogSettings

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

タイプ: AccessLogSettings

必須: いいえ

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

Auth

WebSocket API へのアクセスを制御するための認可を設定します。認可は$connectルートに適用されます。

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

タイプ: WebSocketApiAuth

必須: いいえ

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

DefaultRouteSettings

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

Type: RouteSettings

必須: いいえ

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

Description

WebSocket API の説明。

タイプ: 文字列

必須: いいえ

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

DisableExecuteApiEndpoint

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

型: ブール

必須: いいえ

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

DisableSchemaValidation

デプロイを作成するときにモデルの検証を避けます。

型: ブール

必須: いいえ

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

Domain

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

注記

WebSocket APIs相互 TLS 認証 (MTLS) をサポートしていません。MutualTlsAuthentication またはを指定した場合OwnershipVerificationCertificateArn、 AWS SAM はエラーを返します。

タイプ: WebSocketApiDomainConfiguration

必須: いいえ

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

IpAddressType

API の IP アドレスタイプ。有効な値は IPv4 のみipv4、IPv4 および IPv6 dualstackです。

タイプ: 文字列

必須: いいえ

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

Name

WebSocket API の名前。名前を指定しない場合、は名前 AWS SAM を生成します。

タイプ: 文字列

必須: いいえ

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

PropagateTags

の場合true、が AWS SAM 生成する AWS::ApiGatewayV2::Stageおよび AWS::ApiGatewayV2::DomainNameリソースに Tagsプロパティ AWS SAM を追加します。

型: ブール

必須: いいえ

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

Routes

この WebSocket API のルート設定。ルートは、メッセージが Lambda 関数にルーティングされる方法を定義します。各ルートは、ルートキーと Lambda 関数 ARN で構成されます。

WebSocket APIs$connect、、$disconnectおよびの 3 つの事前定義されたルートをサポートします$default。カスタムルートを定義することもできます。

タイプ: RouteConfiguration

必須: はい

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

RouteSelectionExpression

WebSocket API のルート選択式。詳細については、API Gateway デベロッパーガイドの「ルート選択式」を参照してください。

一般的な値はで$request.body.action、メッセージ本文の actionフィールドに基づいてメッセージをルーティングします。

タイプ: 文字列

必須: はい

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

RouteSettings

この WebSocket API のルート設定。これらの設定は、特定のルートDefaultRouteSettingsのを上書きします。

Type: RouteSettings

必須: いいえ

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

StageName

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

タイプ: 文字列

必須: いいえ

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

StageVariables

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

タイプ: Json

必須: いいえ

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

Tags

この WebSocket API に追加するタグを指定するマップ (文字列から文字列）。タグの有効なキーと値の詳細については、CloudFormation ユーザーガイドのリソースタグを参照してください。

タイプ: マップ

必須: いいえ

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

例

Simple WebSocket API

次の例では、3 つのルートを持つ WebSocket API を作成します。


Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::WebSocketApi
    Properties:
      RouteSelectionExpression: $request.body.action
      Routes:
        $connect:
          FunctionArn: !GetAtt ConnectFunction.Arn
        $disconnect:
          FunctionArn: !GetAtt DisconnectFunction.Arn
        sendMessage:
          FunctionArn: !GetAtt SendMessageFunction.Arn

  ConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.connect
      Runtime: nodejs20.x
      CodeUri: ./src

  DisconnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.disconnect
      Runtime: nodejs20.x
      CodeUri: ./src

  SendMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.sendMessage
      Runtime: nodejs20.x
      CodeUri: ./src

Lambda オーソライザーを使用した WebSocket API

次の例では、Lambda オーソライザーを使用して WebSocket API を作成します。


Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::WebSocketApi
    Properties:
      RouteSelectionExpression: $request.body.action
      Auth:
        AuthType: CUSTOM
        AuthArn: !GetAtt AuthorizerFunction.Arn
        IdentitySource:
          - route.request.header.Authorization
      Routes:
        $connect:
          FunctionArn: !GetAtt ConnectFunction.Arn
        sendMessage:
          FunctionArn: !GetAtt SendMessageFunction.Arn

  AuthorizerFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.authorize
      Runtime: nodejs20.x
      CodeUri: ./src

  ConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.connect
      Runtime: nodejs20.x
      CodeUri: ./src

  SendMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.sendMessage
      Runtime: nodejs20.x
      CodeUri: ./src

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

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

ドキュメントの表記規則

Route53Configuration

WebSocketApiAuth