デバイスデータを自社SaaSに統合
ユースケース
このパターンは、WLTEデバイスの機能があなた自身のプロダクト（マルチテナントSaaS、社内の運用システムなど）の一部である場合に使います。エンドユーザーはあなたのプロダクトと、あなた自身のアカウントシステムを通じてやり取りし、WLTEの認証情報に直接触れることはありません。
- 1つのWLTEアカウントと1つのAPI Clientが、エンドカスタマーごとの認証情報ではなく、デプロイ全体を支えます。
- WLTEアカウント配下のデバイスはフラットであり、テナントという概念はありません。どのデバイスがどの顧客に属するかは、あなた自身が所有し維持するマッピングです。
- ライブイベントは、すべてのエンドカスタマーのページが個別にWLTEへの接続を保持するのではなく、あなた自身のデータパイプライン（データベース、メッセージキュー、自社のWebSocketやWebhook）へ継続的に流れる必要があります。
clientId、clientSecret、アクセストークンをエンドカスタマーに渡さないでください。1つのアカウント配下のデバイスがテナントごとに分離されていると想定しないでください。そうではありません。
推奨アーキテクチャ
WLTEの認証情報を保持するのはあなたのバックエンドだけです。deviceId → tenantId のマッピングを維持し、すべてのテナントを1つのWebSocket接続で処理し、自社システムを通じて配信してください。
段階的な実装
deviceId → tenantId（または自社の顧客・拠点の識別子）のマッピングを設計し維持します。WLTEアカウントはテナントを区別しません——このテーブルが統合全体の中心的なデータ構造になります。- サーバー側で保持する単一のAPI Clientからアクセストークンを取得します。読み取り専用の用途には
device:read、コマンドを発行する場合は加えてdevice:controlまたはdevice:configが必要です。 - デバイス一覧の取得（英語）とデバイスタイプ定義一覧の取得（英語）を呼び出して初期状態のベースラインを構築し、自社のマッピングテーブルを使ってテナントごとのビューに分割します。
- 一度限りのWebSocketチケット（英語）を作成し、テナントごとではなく単一の接続を確立して、接続イベント（英語）、状態変化イベント（英語）、電源イベント（英語）を受信します。
- 各イベントについて、まず
deviceIdでテナントを検索し、自社のストアやキューに書き込むことで、自社のAPI/WebSocket/Webhookがそのテナントのクライアントにプッシュできるようにします。 - エンドカスタマーが制御リクエストを発行した場合は、まず自社の権限システム（WLTEのスコープではなく、プロダクト側のテナントごとの権限）で認可し、その後バックエンドが冪等性キーを付けてリクエストをWLTEにプロキシします。
- 長期保持や請求記録が必要な場合は、コマンド結果とイベントを自分で永続化してください——WLTEはイベント履歴を再生せず、コマンドレコードも短期間しか保持されません。
主なインターフェースとイベント
| 目的 | リファレンス |
|---|---|
| 状態のベースラインを構築 | デバイス一覧の取得（英語） |
| 機能ベースのマルチテナントビュー | デバイスタイプ定義一覧の取得（英語） |
| アカウントへのデバイス追加 | アカウントへのデバイス追加（英語） |
| WebSocket認証 | WebSocketチケットの作成（英語） |
| 接続状況の変化 | デバイス接続イベント（英語） |
| 周辺機器の状態変化 | デバイス状態変化イベント（英語） |
| 電源の喪失・復旧の通知 | デバイス電源イベント（英語） |
| 制御コマンドのプロキシ | リレーコマンドの作成（英語） |
| コマンド結果の照会 | コマンド結果の取得（英語） |
障害と復旧
- レート制限はAPI Client単位でカウントされます。1つのアカウントを共有する複数のテナントは、1つのレート制限予算を共有します——1テナントの高いリクエスト頻度がアカウント全体のクォータを消費する可能性があるため、エンドカスタマーのリクエスト頻度をそのままWLTEに渡すのではなく、自社レイヤーでスロットリングとキューイングを行ってください。
- 上流のWebSocketが失われた場合は、テナントごとではなく、その1つのサーバー側接続だけを再接続してください。再接続中は、下流のデータが古い可能性があるとマークしてください。
- 切断中に欠落したイベントは再送されません。再接続後はRESTで状態のベースラインを再構築してから、イベント駆動の更新を再開してください。
- コマンドレコードと冪等性キーは、WLTE側では約48時間しか保持されません。より長い監査期間や請求期間が必要な場合は、コマンド結果と最終ステータスを自分で永続化してください。
429 RATE_LIMITEDの場合はRetry-Afterを待ってください。自社サービス内でテナントごとに独立したリトライループを実装しないでください。
本番運用上の考慮事項
- エンドカスタマーは、いかなる状況でもWLTEの
clientId、clientSecret、アクセストークンを見たり取得したりしてはいけません——WLTEへのすべての呼び出しは、必ずあなたのバックエンドを経由してください。 - WLTEの4つのスコープ（
device:read/device:control/device:config/device:manage）は、アカウントレベルの粗い権限です。自社の顧客単位のきめ細かい権限モデルの代わりにはなりません——この2つは別々の認可レイヤーです。 deviceId → tenantIdのマッピングは、システムの中で最も重要なテーブルとして扱ってください。デバイスがアカウントに追加・削除されたとき、または顧客が拠点を追加・削除したときは常に同期を維持し、データが誤ったテナントに混入しないようにしてください。- レート制限の予算は事前に計画してください。テナント数はリクエスト量を線形に増やしますが、アカウントのレート制限はそれに合わせて増えません。
- 利用可能なスコープの組み合わせについては認可スコープ（英語）、レート制限の詳細についてはレート制限とリトライ（英語）を参照してください。