# ソリューションの仕組み
<a name="how-the-solution-works"></a>

 このセクションでは、AWS の Virtual Waiting Room のワークフローについて、概要を説明します。ウェブサイトに待合室を構築し、カスタマイズや統合を行う方法の詳細については、[GitHub 上のデベロッパーガイド](https://github.com/aws-solutions/aws-virtual-waiting-room/blob/main/docs/developer-guide.md)を参照してください。

 待合室のパブリック API は、今あるサイトで構築されているセキュリティ境界の背後に配置することも、認証なしで使用することもできます。待合室をウェブサイトと統合するために使用するアプローチによっては、ユーザーが待合室に移動してキュー内の位置を取得する前に、まずウェブサイトに対する認証が必要になる場合があります。

 待合室に入って他のリクエストを行うには、クライアントソフトウェアが Event ID を取得する必要があります。Event ID は、パブリック API とプライベート API に対するほとんどのリクエストに必要な一意の ID です。Event ID は、コア API スタックのインストール時に設定されます。オペレーション中、Event ID は、待合室ページを介して URL パラメータまたは Cookie として提供できます。認証トークンのリクエストの一部として提供することも、別の方法を利用してクライアントに配布することもできます。

 特定の API コールを行うために、クライアントが Event ID と Request ID の両方を必要とする場合があります。Request IDは、順番を待つ個々のクライアントを表す一意の ID であり、待合室から発行されます。

 次の手順では、まずキューに入り、キューの進行を待ち、ウェブサイトへのアクセストークンを取得して待合室から出るという API リクエストの流れを説明しています。

 **ユーザーが待合室に入室する:**

1.  待合室の入口を表す画面またはページがユーザーに表示されます。ユーザーがキューに入ることを選択し、クライアントソフトウェア (ブラウザ、モバイル、デバイス) によって、キュー位置をリクエストする `assign_queue_num` パブリック API が呼び出されます。

1.  API リクエストは、API Gateway によってすぐに Amazon SQS キューに配信されます。

1.  `assign_queue_num` API コールは、リクエストがキューに配置されると応答を返します。クライアントは一意の Request ID を受け取ります。この値は、後でキューの位置、リクエストの時刻、アクセストークンを取得するのに使用できます。

1.  `AssignQueueNum` Lambda 関数は、SQS キューから最大 10 件のリクエストのバッチを受け取ります。Lambda サービスは呼び出しをファンアウトして、複数バッチのリクエストを処理します。

1.  `AssignQueueNum` Lambda 関数は、バッチ内の各メッセージを検証し、Elasticache (Redis OSS) のキューカウンターを増分して、各リクエストおよび関連するキュー位置を Elasticach (Redis OSS) に保存します。

1.  各メッセージは、正常に処理されると削除されます。エラー状態に関連するメッセージは、後のバッチで 1 回再処理されます。2 回目に失敗すると、これらは [CloudWatch アラーム](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)に接続されたデッドレターキューに送信されます。

1.  クライアントは、`assign_queue_num` コールから Request ID を受け取ると、`queue_num` API のポーリングを開始できます。クライアントは、Event ID と Request ID を `queue_num` API に送信し、キュー位置の数値か、リクエストがまだ処理されていないことを示すレスポンスを受け取ります。大規模なイベント中には、クライアントによるこのコールが複数回必要になることもあります。`GetQueueNum` Lambda 関数は、API Gateway によって呼び出され、DynamoDB からキュー内のクライアントの位置を数値で返します。

**ユーザーが待合室で待機する:**

1.  クライアントは、キュー内の位置を取得した後、一定の間隔で `serving_num` API のポーリングを開始できます。`serving_num` API は Event ID で呼び出され、キューの現在の処理待ち順序を返します。`serving_num` API からのレスポンスは、クライアントに、待合室から最終的なトランザクションが実行される実際のターゲットサイトに移動できるタイミングを伝えます。`GetServingNum` Lambda 関数は、待合室での現在の処理待ち順序を返します。

1.  処理待ちの順序がクライアントのキュー (リクエスト) 位置以上であれば、クライアントはパブリック API から JSON Web Token (JWT) をリクエストできます。このトークンをターゲットサイトで使用して、トランザクションを完了することができます。`generate_token` API は、Event ID と Request ID を使用して呼び出されます。API Gateway は、パラメータを使用して `GenerateToken` Lambda 関数を呼び出します。

1.  `GenerateToken` Lambda 関数は、リクエストを検証し、このトークンが以前に生成されたかどうかを確認します。Lambda 関数は、一致するトークンを DynamoDB テーブルで照会します。見つかった場合、そのトークンは呼び出し元に返され、再生成されません。このプロセスにより、1 つの Request ID で、新しい有効期限を持つ複数の異なるトークンが生成されることを防ぎます。

1.  トークンが DynamoDB で見つからない場合、Lambda 関数はトークンを作成するためのキーを取得し、Event ID とクライアントの Request ID を使用して DynamoDB にトークンを保存します。Lambda 関数は EventBridge にイベントを書き込み、新しいトークンが生成されたことを通知します。Lambda 関数は、イベントに対して生成されたトークンの数を追跡する Elasticache (Redis OSS) カウンターを増分します。

1.  `queue_pos_expiry` がオンになっている場合は、クライアントは `GetQueuePositionExpiryTime` Lambda 関数を呼び出す `queue_pos_expiry` API を呼び出すことで、有効期限が切れるまでの残り時間をクエリすることができます。

 **ユーザーが待合室から退出する:**

1.  クライアントは、トークンを受け取ると、ターゲットサイトに入りトランザクションを開始します。インフラストラクチャで JWT との統合がどのようにサポートされるかによって、クライアントはリクエストヘッダー、cookie、またはその他の方法でトークンを提示する必要があります。API Gateway のオーソライザーを使用すると、クライアントのリクエストに含まれるトークンを検証できます。Virtual Waiting Room on AWS のトークンは、JWT を検証および管理するための商用またはオープンソースのあらゆるライブラリで使用できます。トークンが有効であれば、クライアントはトランザクションを続行できます。

1.  クライアントがトランザクションを完了した後、クライアントのトークンのステータスを更新するためにプライベート API が呼び出され、DynamoDB 内で完了となります。

 **キュー位置の有効期限:**

1.  この機能をアクティブにすると、特定のキュー位置に対応する Request ID は、指定された時間間隔でのみトークンを生成できます。

 **キュー位置の有効期限が切れるとサービングカウンターを増分する:**

1.  この機能をアクティブにすると、トークンを生成できなかった有効期限切れのキュー位置に基づいて、サービングカウンターが自動的に増分されます。