WebSocket接続の設定
主なメリット
-
リアルタイム通信
-
API呼び出しの削減
-
複数のワークフローの効率的な処理
-
イベント駆動型アーキテクチャのサポート
WebSocketとREST／SOAPの違い
|
機能 |
REST／SOAP |
WebSocket |
|
接続の種類 |
ステートレス |
継続的 |
|
通信 |
要求 → 応答 |
継続的（双方向） |
|
再接続 |
要求ごとに必要 |
不要 |
|
ユースケース |
標準的なAPI呼び出し |
リアルタイム更新 |
-
REST／SOAPでは、各要求は独立しており、すぐに応答が返されます。
-
WebSocketでは、一度接続すると、手動で切断するまで接続は有効なまま維持されます。
主なユースケース
-
ライブダッシュボード（例：チケット数のリアルタイム更新）
-
チャットアプリケーション／チャットボット
-
リアルタイム通知（例：取引の更新）
-
ライブデータストリーム（例：スポーツのスコア）
WebSocketエンドポイントの設定
QntrlでWebSocketを設定するには、以下の手順を実行します。
1. WebSocketに移動します。
-
Qntrlにログインします。
-
左側のパネルにある［Webサービス］アイコン
をクリックします。
-
［受信］で［WebSocket］を選択します。
2. 接続設定で基本情報を入力します。
-
［接続名］：WebSocket接続を識別するための名前
-
［WebSocket URL］：接続の確立に使用するエンドポイントURLです。
-
［認証の種類］：OAuthまたはAPIキー
-
接続を確立する際は、次のクエリーパラメーターを渡します：wss://<URL>?auth_type=<auth_type>
-
auth_type=oauth→ OAuth認証
-
auth_type=apikey→ APIキー認証
-
［メッセージルーティングパス］– 受信メッセージのルーティングに使用するJSONパスです（例：$.タブ）
3. 接続イベントごとのシステムの動作を定義します。 ［リソースの種類］ドロップダウンには、タブの種類が「Webservice WebSocket」のすべてのリソースが表示されます。
-
［接続ルート］：クライアントが接続したときに実行するアクション
-
［切断ルート］：クライアントが切断したときに実行するアクション
-
［デフォルトルート］：特定のメッセージルートに一致しない場合のフォールバックアクション
上記のそれぞれについて、以下を選択します。
-
リソース種別（例：関数）
-
リソース（実行する特定の関数または操作）
4. メッセージルーティング：受信メッセージを動的に処理します。リソース選択パスから値を読み取り、一致した値に基づいて操作をトリガーします。
各ルートで、次の項目を定義します。
-
ルート値：要求から照合する値
-
リソース種別：操作の種類
-
リソース：実行する操作
入力JSONの例。
{
'タブ': 'task_engine'
}
設定。
-
リソース選択パス：$.タブ
-
ルート値ごとの設定。
-
task_engine→関数Aを実行
-
db_engine→関数Bを実行
-
一致なし→デフォルトルートを実行
これにより、1つのWebSocketエンドポイントで複数のワークフローを処理できます。
5. ポリシー：ポリシーでは、接続ごとに許可されるメッセージ数を制御します。
-
既存のポリシーを選択するか、［新しいポリシーを追加］をクリックします
-
次の詳細を入力します。
-
ポリシー名：ポリシーの名前
-
許可される要求数：許可する最大メッセージ数
-
時間枠（分）：時間枠を分単位で入力します
-
エラーコード：制限を超えた場合に返されます
-
メッセージ：表示されるエラーメッセージ
-
ポリシーを作成するには、［保存］をクリックします
-
レートポリシー設定を更新するには、項目の横にある編集（✎）アイコンをクリックします。
6. すべての設定が完了したら、［保存］をクリックします。
WebSocketセッションの確立
セッションを確立するには、次のURLを使用して接続します：wss://<URL>?auth_type=<auth_type>
接続成功時
-
セッションIDがレスポンスヘッダーで返されます
-
このセッションはメッセージ交換に使用されます
任意パラメーター
-
session_id（ヘッダー）：再接続時にセッションIDを渡すことで、既存のセッションを再利用し、同じセッションを保持できます。
-
session_name（クエリパラメーター）：セッションに一意の名前を割り当てます。後でそのセッションを識別し、そのセッションにメッセージを送信するために使用できます。
セッションの動作
-
メッセージの交換が1.5分間行われない場合、セッションは自動的に切断されます
WebSocketの使用
メッセージの送信（クライアント→Qntrl）
-
有効な接続を介してメッセージが継続的に送信されます
-
メッセージルートに基づいてルーティングされます
メッセージの送信（Qntrl→クライアント）
Codex関数（スタンドアロン、保存後のジョブなど）からメッセージを送信できます。
-
セッションIDを使用：WebSocket.sendMessage(<session_id>, <message>);
-
セッション名を使用：WebSocket.sendMessagebyName(<websocket_id>, <session_name>, <message>);
-
ユーザーID（OAuth）を使用：WebSocket.sendMessageForUser(<websocket_id>, <user_id>, <message>);
接続の表示と管理
-
WebSocketリソース一覧からWebSocketを選択します。
-
WebSocketの詳細セクションで、必要に応じて設定を変更し、［保存］をクリックして変更を適用できます。
-
セッションの詳細セクションに移動し、すべての有効な接続と過去の接続、およびそれぞれのステータスを表示します。
-
［ステータス］の切り替えを使用して、セッションを接続または切断します。
-
セッションが切断されると、その接続にはメッセージが配信されなくなります。
ユーザー別通知（OAuth）
OAuthを使用する場合。
-
接続はユーザーに関連付けられます
-
特定のユーザーに通知を送信できます
例
-
イベント：トランザクションが完了
-
処理：ユーザーにメッセージを送信
-
結果：ユーザーはすべての有効なセッションで即時通知を受信します