バックエンドサービスでの @connections コマンドの使用

バックエンドサービスは次の WebSocket 接続 HTTP リクエストを使用して、接続されたクライアントへのコールバックメッセージの送信、接続情報の取得、またはクライアントの切断を行うことができます。

重要

これらのリクエストは IAM 認可を使用するため、署名バージョン 4 (SigV4) を使用して署名する必要があります。これを行うには、API Gateway 管理 API を使用します。詳細については、「ApiGatewayManagementApi」を参照してください。

次のコマンドでは、{api-id} を実際の API ID に置き換える必要があります。この ID は API Gateway コンソールに表示されるか、AWS CLI create-api コマンドから返されます。このコマンドを使用する前に接続を確立する必要があります。

コールバックメッセージをクライアントに送信するには、以下を使用します。

POST https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}

以下の例のように、Postman を使用するか、awscurl を呼び出すことで、このリクエストをテストできます。

awscurl --service execute-api -X POST -d "hello world" https://{prefix}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}

次の例のようにコマンドを URL でエンコードする必要があります。

awscurl --service execute-api -X POST -d "hello world" https://aabbccddee.execute-api.us-east-1.amazonaws.com/prod/%40connections/R0oXAdfD0kwCH6w%3D

クライアントの最新の接続ステータスを取得するには、以下を使用します。

GET https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}

クライアントを切断するには、以下を使用します。

DELETE https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}

統合で $context 変数を使用して、コールバック URL を動的に構築できます。例えば、Node.js Lambda 関数で Lambda プロキシの統合を使用する場合は、次のように URL を構築し、接続されたクライアントにメッセージを送信できます。

import {
  ApiGatewayManagementApiClient,
  PostToConnectionCommand,
} from "@aws-sdk/client-apigatewaymanagementapi";

export const handler = async (event) => {
  const domain = event.requestContext.domainName;
  const stage = event.requestContext.stage;
  const connectionId = event.requestContext.connectionId;
  const callbackUrl = `https://${domain}/${stage}`;
  const client = new ApiGatewayManagementApiClient({ endpoint: callbackUrl });

  const requestParams = {
    ConnectionId: connectionId,
    Data: "Hello!",
  };

  const command = new PostToConnectionCommand(requestParams);

  try {
    await client.send(command);
  } catch (error) {
    console.log(error);
  }

  return {
    statusCode: 200,
  };
};

WebSocket API にカスタムドメイン名を使用する場合は、関数コードから stage 変数を削除します。

コールバックメッセージを送信する場合、Lambda 関数には API ゲートウェイ管理 API を呼び出すアクセス許可が必要です。接続が確立される前、またはクライアントの接続が切断された後にメッセージを投稿すると、GoneException を含むエラーが表示される場合があります。