切断と電源イベントを監視
ユースケース
このパターンは、バックエンドがデバイスの状態を繰り返しポーリングすることなく、可用性を更新したり、アラートを発報したり、サポートされている電源変化のシグナルを記録したりする必要がある場合に使います。
device.connection.onlineとdevice.connection.offlineは接続状況の変化を表します。device.power.lostは、その信号を提供するデバイスからの電源喪失シグナルを報告します。device.power.restoredは電源の復旧を報告しますが、ネットワーク接続が利用可能であることを意味するものではありません。- デバイスの機種によって、電源検知の挙動が必ずしも同じとは限りません。プロダクトでこれらのアラートを約束する前に、デバイスタイプ定義と納品されたデバイスのドキュメントを確認してください。明示的に対応が記載されていない場合は、対応していると推測しないでください。
推奨フロー
WebSocketはタイムリーな通知を提供しますが、永続的な記録システムではありません。現在の状態は自分のサービス側で保持し、イベントのギャップが発生した後はRESTから復元してください。
段階的な実装
- デバイス一覧の取得（英語）でアカウントの初期状態を構築します。
- 電源関連のUIやアラートを有効にする前に、デバイスタイプ定義一覧の取得（英語）と納品されたデバイスのドキュメントを確認してください。一般的な操作一覧は、電源検知に対応していることの証明にはなりません。
- WebSocketチケット（英語）を作成し、接続してから、プロトコルのPing/Pongと
session.pingを開始します。 device.connection.offlineを受け取ったら、そのデバイスを制御可能として表示するのをやめ、occurredAtを記録します。device.connection.onlineを受け取ったら接続の復旧をマークしますが、すべての周辺機器の状態がすでに同期済みだとは想定しないでください。現在の状態が必要な場合はデバイスを更新してください。device.power.lostを受け取ったらイベントを永続化してアラートを発報します。device.power.restoredを受け取ったら電源アラートを閉じることができますが、デバイスを制御可能として扱う前にdevice.connection.onlineを待ってください。- 電源イベントには構造化されたトピックとタイムスタンプのみを使ってください。ファームウェアの生テキストを解析したり、それに基づいて分岐したりしないでください。
- 再接続後は、RESTでアカウントのベースラインを復元し、即座の確認が必要な重要なデバイスだけを照会してください。
主なインターフェースとイベント
| 目的 | リファレンス |
|---|---|
| 現在のアカウントのベースライン | デバイス一覧の取得（英語） |
| 1台のデバイスを確認 | デバイスの取得（英語） |
| オンライン・オフラインイベント | デバイス接続イベント（英語） |
| 電源の喪失・復旧のセマンティクス | デバイス電源イベント（英語） |
| ハートビートと復旧 | ハートビートと再接続（英語） |
障害と復旧
- 接続の切断とハートビートのタイムアウトを検知し、上限のある指数バックオフとランダムなジッターで再接続してください。
wsTicketを再利用しないでください。各接続試行の直前に新しいものを作成してください。- イベントは再送されません。再接続後は、イベントが発生しなかったと想定せず、現在の状態を再構築してください。
- イベント配信は、リトライや再接続の境界付近で重複することがあります。利用可能なトピック、
deviceId、タイムスタンプ、結果の状態を使ってハンドラーを冪等にしてください。イベント契約で定義されていないフィールドに依存しないでください。 - 電源イベントと接続イベントには順序保証がなく、どちらか一方だけが届くこともあります。
online/offlineから電源の変化を推測しないでください。
本番運用上の考慮事項
- 可観測性のために、イベントの受信時刻をデバイスの
occurredAtとは別に保存してください。 - 再接続の集中が重複したインシデントを生まないよう、アラート抑制と復旧のルールを定義してください。
- WebSocketをライブ更新チャネルとして、RESTを状態復旧の経路として扱ってください。
- デバイスのオンボーディング時に電源イベント対応を確認してください。別のデバイスタイプがそのイベントを報告しているという理由だけで対応していると推測しないでください。