デバイス監視ダッシュボードを構築
ユースケース
このパターンは、HTTPトラフィックを予測可能に保ちながら、デバイスの接続状況と周辺機器の状態を表示するアカウントレベルのダッシュボードに使います。
- 初期表示、ページング、バックグラウンド同期にはRESTのデバイス一覧を使います。
- ユーザーが明示的に詳細ビューを更新する場合や、操作の確認が必要な場合は単一デバイスの照会を使います。
- 接続、リレー、デジタル入力の継続的な状態変化にはWebSocketイベントを使います。
すべてのデバイスを継続的にHTTPでポーリングしないでください。
推奨アーキテクチャ
deviceId ごとに1つの状態レコードを維持してください。実行時の状態をマージする際は stateUpdatedAt を使い、古いデータが新しいデータを上書きしないようにします。接続イベントは接続状況を更新し、device.state.changed の changes は影響を受けたリレーやデジタル入力を示しますが、peripherals は差分パッチではなく完全な状態ブロックです。アナログやセンサーの値は、ユーザーが更新した時、またはビジネスフローが必要とする時に読み取り、すべてのデバイスを高頻度でポーリングしないでください。
段階的な実装
device:readを持つアクセストークンを取得します。- デバイス一覧の取得（英語）を呼び出してページングをたどり、各デバイスの
deviceType、status、周辺機器、stateUpdatedAtを保存します。 - デバイスタイプ定義一覧の取得（英語）を取得し、各
deviceTypeをその機能定義に対応付けます。これらの定義は描画のたびにリクエストせず、キャッシュしてください。 - 一度限りのWebSocketチケット（英語）を作成し、接続を確立して、ドキュメント化されたハートビートフローを開始します。
device.connection.online、device.connection.offline、device.state.changedイベントを対応するデバイスレコードに反映します。- ユーザーが1台のデバイスについて明示的に最新データを要求した場合は、デバイスの取得（英語）を呼び出すか、
device.state.get（英語）を送信します。 - 切断またはプロセス再起動の後は、新しいチケットで再接続し、ライブビューを再び信頼する前にRESTでベースラインを再構築します。ビジネス上重要なデバイスだけを個別に更新してください。
主なインターフェースとイベント
| 目的 | リファレンス |
|---|---|
| 初期一覧とページング | デバイス一覧の取得（英語） |
| 機能ベースのUI | デバイスタイプ定義一覧の取得（英語） |
| 明示的な単一デバイス更新 | デバイスの取得（英語） |
| WebSocket認証 | WebSocketチケットの作成（英語） |
| 接続状況の変化 | デバイス接続イベント（英語） |
| 周辺機器の状態変化 | デバイス状態変化イベント（英語） |
障害と復旧
- WebSocketが失われたら、ライブチャネルを利用不可としてマークし、指数バックオフとジッターで再接続し、試行ごとに新しい
wsTicketを作成してください。 - 切断中に欠落したイベントは再送されません。再接続後はRESTで状態のベースラインを再構築してください。
- イベントと照会が競合した場合は、より新しい
stateUpdatedAtを持つ状態を採用してください。 429 RATE_LIMITEDの後はRetry-Afterを待ってください。切断されたWebSocketを補うためにデバイス単位のポーリングに切り替えないでください。OFFLINEのデバイスには、最後に同期された周辺機器の状態が含まれている場合があります。接続状況と状態の鮮度は別々に表示してください。
本番運用上の考慮事項
deviceIdごとに正規化した状態を保存し、センサー値はindex + typeで識別してください。- イベントの適用を冪等にしてください。接続イベントは
occurredAtを、状態イベントはstateUpdatedAtを提供します。現在のレコードにすでに反映されている古い更新は無視してください。 - WebSocketには履歴の再生がないため、ビジネス上重要なイベントは速やかに永続化してください。
- 認証情報やトークンをログに残さずに、再接続の試行、イベントの遅延、REST同期の失敗、
requestIdの値を監視してください。