WebSocket API のルートの操作

WebSocket API では、受信する JSON メッセージは設定したルートに基づいてバックエンド統合に転送されます (JSON 以外のメッセージは、設定した $default ルートに転送されます)。

ルートにはルートキーが含まれます。これは、ルート選択式が評価されたときに予期される値です。属性 routeSelectionExpression は、API レベルで定義されます。メッセージペイロードに存在することが予期される JSON プロパティを指定します。ルート選択式の詳細については、「ルート選択式」を参照してください。

たとえば、JSON メッセージに action プロパティが含まれていて、このプロパティに基づいてさまざまなアクションを実行する場合、ルート選択式は ${request.body.action} のようになります。ルーティングテーブルでは、このテーブルで定義したカスタムルートキーの値に対して、action プロパティの値を一致させることによって、実行するアクションを指定します。

3 つの事前定義されたルート ($connect、$disconnect、および $default) を使用できます。さらに、カスタムルートを作成することができます。

API Gateway は、クライアントと WebSocket API 間の永続的な接続が開始されたときに、$connect ルートを呼び出します。
API Gateway は、クライアントまたはサーバーが API から切断したときに、$disconnect ルートを呼び出します。
API Gateway は、一致するルートが見つかった場合、メッセージに対してルート選択式が評価された後でカスタムルートを呼び出します。この一致により、呼び出される統合が決まります。
ルート選択式をメッセージに対して評価できない場合や、一致するルートが見つからない場合、API Gateway は $default ルートを呼び出します。

ルート選択式

ルート選択式は、サービスが受信メッセージについてたどるルートを選択するときに評価されます。このサービスでは、routeKey が評価された値に完全に一致するときにルートが使用されます。何も一致せず、$default ルートキーを持つルートが存在する場合は、そのルートが選択されます。評価された値と一致するルートがなく、$default ルートもない場合、サービスからエラーが返されます。WebSocket ベースの API の場合、式の形式は $request.body.{path_to_body_element} である必要があります。

たとえば、次の JSON メッセージを送信するとします。


{
    "service" : "chat",
    "action" : "join",
    "data" : {
        "room" : "room1234"
   }
}

action プロパティに基づいて、API の動作を選択する必要があります。その場合は、次のルート選択式を定義できます。


$request.body.action

この例で request.body は、メッセージの JSON ペイロードを参照し、.action が JSONPath 式になります。JSON パス式は request.body の後に使用できますが、結果は文字列化されることに注意してください。たとえば、JSONPath 式は 2 つの要素の配列を返し、文字列 "[item1, item2]" として表示されます。このため、式は配列やオブジェクトではなく値に対して評価することをお勧めします。

静的な値を使用するか、複数の変数を使用できます。以下の表に示しているのは、例と上記のペイロードに対して評価された結果です。

式	評価結果	説明
`$request.body.action`	`join`	1 つのラップ解除された変数
`${request.body.action}`	`join`	1 つのラップされた変数
`${request.body.service}/${request.body.action}`	`chat`/`join`	静的な値を持つ複数の変数
`${request.body.action}-${request.body.invalidPath}`	`join-`	JSONPath が見つからない場合、変数は "" として解決されます。
`action`	`action`	静的な値
`\$default`	`$default`	静的な値

評価された結果は、ルートを見つけるために使用されます。一致するルートキーがあるルートがある場合、そのルートがメッセージを処理するために選択されます。一致するルートが見つからなかった場合、API Gateway は $default ルートを見つけようとします (利用可能な場合)。$default ルートが定義されていない場合、API Gateway はエラーを返します。

API Gateway で WebSocket API のルートを設定する

新しい WebSocket API を初めて作成するときは、3 つの事前定義されたルート ($connect、$disconnect、$default) があります。これらのルートは、コンソール、API、または AWS CLI を使って作成できます。必要に応じて、カスタムルートを作成することができます。詳細については、「API Gateway での WebSocket API について」を参照してください。

注記

CLI では、統合を作成する前または後にルートを作成したり、複数のルートで同じ統合を再利用したりできます。

API Gateway コンソールを使用したルートの作成

API Gateway コンソールを使用してルートを作成するには

API Gateway コンソールにサインインし、[API]、[Routes (ルート)] の順に選択します。
[ルートの作成] を選択します。
[ルートキー] に、ルートキー名を入力します。定義済みのルート ($connect、$disconnect、および$default) またはカスタムルートを作成できます。

注記
カスタムルートを作成する場合、ルートキー名に $ プレフィックスは使用しないでください。このプレフィックスは事前定義されたルートのために予約されています。
ルートの統合タイプを選択して設定します。詳細については、「API Gateway コンソールを使用して WebSocket API 統合リクエストを設定する」を参照してください。

AWS CLI を使用したルートの作成

AWS CLI を使用してルートを作成するには、次の例に示すように、create-route を呼び出します。


aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default

出力例:


{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteKey": "$default",
    "RouteId": "1122334"
}

`$connect` のルートリクエスト設定の指定

API の $connect ルートを設定するときは、以下のオプション設定を使用して、API の認証を有効にできます。詳細については、「$connect ルート」を参照してください。

認可: 認証が必要ない場合は、NONE を指定できます。それ以外の場合は、以下を指定できます。
- API へのアクセスを制御するために標準の AWS IAM ポリシーを使用するには、AWS_IAM を指定します。
- 以前に作成した Lambda オーソライザー関数を指定して API の認証を実装するには、CUSTOM を指定します。オーソライザーは、独自の AWS アカウントまたは別の AWS アカウントに設定できます。Lambda オーソライザーの詳細については、「API Gateway Lambda オーソライザーを使用する」を参照してください。
  
  注記
  API Gateway コンソールで、CUSTOM 設定は「API Gateway コンソールを使用した Lambda オーソライザーの設定」で説明したオーソライザー関数を設定した後でのみ表示されます。
重要
[認証] 設定は、$connect ルートだけではなく、API 全体に適用されます。$connect ルートは、すべての接続で呼び出されるため、他のルートを保護します。
[API キーの必要性]: 必要に応じて、API の $connect ルートの API キーを要求できます。API キーを使用量プランと一緒に使用して、API へのアクセスを制御、追跡できます。詳細については、「API キーを使用した使用量プランの作成と使用」を参照してください。

API Gateway コンソールを使用して `$connect` ルートリクエストをセットアップする

API Gateway コンソールを使用して WebSocket API の $connect ルートリクエストを設定するには

API Gateway コンソールにサインインし、[API]、[Routes (ルート)] の順に選択します。
[ルート] で、$connect を選択するか、API Gateway コンソールを使用したルートの作成に従って $connect ルートを作成します。
[ルートリクエスト設定] セクションで、[編集] を選択します。
[承認] では、認証タイプを選択します。
$connect ルートで API を必須にするには、[API キーを要求する] を選択します。
[Save changes] (変更の保存) をクリックします。

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

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

ドキュメントの表記規則

作成と設定

WebSocket API のルートレスポンスを設定する