はじめに

このページでは、統合作業を始める前に押さえておくべき基本モデルを説明します。すべてのエンドポイントパラメータを網羅するものではありません。代わりに、WLTE OpenAPIで使われる主要なオブジェクト、リクエストパターン、デバイスの状態モデル、コマンドのライフサイクルを解説します。

すぐに最初のリクエストを実行したい場合は、クイックスタートへ進んでください。

WLTE OpenAPIとは

WLTE OpenAPIは、サーバーサイドのシステム向けに設計されています。あなたのプラットフォームからWLTEデバイスの読み取り、制御、監視ができます。

主な機能は次のとおりです。

アカウントがアクセス可能なデバイスの一覧取得
1台のデバイスの状態と周辺機器データの読み取り
デバイスタイプ定義とサポートされている操作の読み込み
リレー、RS485、設定コマンドの送信
コマンド結果の照会
WebSocket経由でのリアルタイムなデバイスイベントの受信

主要な概念

概念	説明
API Client	Developer Consoleで1つのアプリケーションごとに作成される呼び出し元のID
`clientId` / `clientSecret`	アクセストークンを取得するために使うサーバーサイドの認証情報
アクセストークン	保護されたエンドポイントを呼び出すために使う、有効期限の短いトークン
デバイス	アカウントがアクセスできるWLTEデバイス
デバイスタイプ	サポートされている周辺機器と操作を記述するデバイス定義
周辺機器の状態	リレー、デジタル入力、センサー、アナログ入力、その他周辺機器の状態
コマンド	リレー制御、RS485の透過送信、設定変更など、1つのデバイス操作リクエスト
WebSocketイベント	状態変化、接続状態の変化、電源イベントなどをリアルタイムに通知するもの

統合モデル

clientSecret はサーバー側で保管し、アクセストークンの取得に使ってください。ブラウザ、モバイルアプリ、その他のクライアントで clientSecret を直接保持してはいけません。

REST APIとWebSocket

REST APIとWebSocketは互いの代替ではなく、それぞれ異なる役割を担います。

シナリオ	推奨方法
アクセストークンの取得	REST API
デバイス一覧の取得	REST API
デバイスタイプ定義の読み込み	REST API
デバイスコマンドの送信	接続モデルに応じてREST APIまたはWebSocket
コマンド結果の照会	REST API
1台のデバイスを明示的に更新	REST APIの `GET /devices/{deviceId}` またはWebSocketの `device.state.get`
オンライン・オフライン・電源・状態変化イベントの監視	WebSocket

初めて統合する際は、REST APIで認証・デバイス一覧・1台のデバイス状態照会を検証してください。リアルタイムイベントが必要になったらWebSocketを追加します。

より詳しい比較はREST APIかWebSocketかを参照してください。

デバイスの状態モデル

デバイスの状態は、ユースケースに応じて解釈する必要があります。

データ	ユースケース	説明
デバイス一覧の状態	一覧表示、ダッシュボード、バックグラウンド同期	プラットフォームがすでに同期済みのデータで、一括表示に適しています
単一デバイスのリアルタイム状態	詳細ページの更新、操作の前後確認	サーバーが能動的に1台のデバイスを更新しようとします
WebSocketイベント	継続的な状態監視	接続状態の変化、電源イベント、周辺機器の変化などをリアルタイムに通知します

すべてのデバイスに対して高頻度なHTTPポーリングで周辺機器・オフライン状態・電源変化を監視してはいけません。継続的な監視にはWebSocketイベントを使用してください。再接続後は、デバイス一覧または単一デバイスのステータスエンドポイントで重要な状態を再構築してください。

コマンドモデル

デバイスコマンドは通常、次の2つの段階を経ます。

プラットフォームがリクエストを受け付けます。
デバイスが最終結果を確認するか、待機ウィンドウがタイムアウトします。

一般的なステータス:

ステータス	意味
`SUCCESS`	デバイスが結果を確認しました
`TIMEOUT`	待機ウィンドウ内に最終確認が届きませんでした
`FAILED`	コマンドが失敗したか、明示的に拒否されました
`SENT`	コマンドは送信済みですが、まだ終端ステータスがありません。既存のコマンドを照会したときによく見られます

TIMEOUT は、デバイスがコマンドを実行しなかったことを証明するものではありません。確認が遅延または失われている間に、デバイスが実行を完了していた可能性があります。副作用のあるコマンドについては、タイムアウト後にリクエストを盲目的に繰り返さないでください。まず現在のデバイス状態を読み取ってから、次の対応を決めてください。

権限とセキュリティモデル

API Clientはスコープでアクセスを制御します。一般的なルール:

読み取り専用の照会には通常 device:read が必要です
デバイス制御には通常 device:control が必要です
デバイス設定には通常 device:config が必要です
デバイス管理には通常 device:manage が必要です

リクエストが AUTH_SCOPE_DENIED を返した場合、レスポンスに不足している権限が示されます。Developer ConsoleでAPI Clientの権限を更新し、新しいアクセストークンを取得してください。

セキュリティ境界:

clientSecret はサーバー上にのみ保管してください
clientSecret、アクセストークン、WebSocketチケットをフロントエンドコード、公開リポジトリ、ログに書き込まないでください
API Clientが無効化または削除されると、既存のトークンは拒否されます
シークレットをローテーションした後は、サーバー側の設定を更新して新しいトークンを取得してください

推奨される統合手順

Developer ConsoleでAPI Clientを作成します。
Brunoを使って認証・デバイス一覧・1台のデバイス状態照会を検証します。
デバイスタイプ定義を読み込み、サポートされている周辺機器と操作を確認します。
プロダクトのワークフローに応じてREST API、WebSocket、またはその両方を選択します。
SDKまたは直接のHTTP/WebSocket呼び出しでサーバーから統合します。
本番投入前に、権限、レート制限、リトライ、冪等性、ログのマスキングを確認します。

次のステップ: クイックスタートへ進んでください。

はじめに ​

WLTE OpenAPIとは ​

主要な概念 ​

統合モデル ​

REST APIとWebSocket ​

デバイスの状態モデル ​

コマンドモデル ​

権限とセキュリティモデル ​

推奨される統合手順 ​