よくある質問

このページでは、統合作業中に最もよくある問題を整理しています。まずは今の症状に最も近いものから確認してください。エンドポイントのスキーマ、パラメータ、完全なエラー一覧はリファレンスドキュメントに記載しています。

症状から探す

見えている状況	まずここから
APIキーがなく、どこで作成すればよいかわからない	APIコールがまだ動かない
トークンの発行に失敗する、または401/403が返る	APIコールがまだ動かない
デバイスが見当たらない、または状態が最新に見えない	デバイスデータがおかしく見える
周辺機器・オフライン状態・電源喪失を継続的に監視したい	デバイスデータがおかしく見える
コマンドは受け付けられたが、デバイスが応答しない、またはタイムアウトした	デバイス操作が期待どおりに完了しない
WebSocketが接続できない、頻繁に切断される、イベントが欠落する	リアルタイム接続が不安定
REST APIとWebSocketのどちらを使うべきか迷っている	REST APIかWebSocketか
リクエストが429、503、またはゲートウェイ利用不可を返す	リクエストが制限されている、またはサービスが一時的に利用できない
ドキュメントを確認しても問題が解決しない	トラブルシューティングの詳細を準備する

APIコールがまだ動かない

API clientの作成方法と認証情報の取得方法は？

WLTE Developer ConsoleでAPI clientを作成します。

1. Developer Consoleにサインインします: https://developer.svnwi.com/wlte
2. アプリケーションを開き、API client管理に移動します。
3. API clientを作成し、統合に必要な最小限の権限を選択します。
4. 生成された clientId と clientSecret を保存します。

API clientを作成すると、clientId と clientSecret が発行され、この2つを組み合わせてアクセストークンを取得します。

clientSecret は作成時またはローテーション時にのみ表示されます。すぐにサーバー側のシークレットストレージに保存してください。紛失した場合は、元の値を再表示できないため、シークレットをローテーションしてください。API Keysを取得を参照してください。

アクセストークンの発行に失敗する

次の項目を順に確認してください。

1. API clientが存在し、有効化されている。
2. clientId と clientSecret が同じclientのものである。
3. アプリケーションとアカウントがアクティブである。
4. URL、メソッド、リクエスト本文がアクセストークンの作成（英語）と一致している。

認証にもレート制限が適用される場合があるため、無効な認証情報で無限に再試行しないでください。

レスポンスコードが AUTH_INVALID

認証情報、またはその所有者の現在の状態が無効です。よくある原因は、認証情報の誤り、無効化・削除されたAPI client、無効化されたアプリケーション、無効なアカウント状態です。

最近シークレットをローテーションした場合は、新しいシークレットを使用しているか確認してください。message ではなく code で分岐してください。

レスポンスコードが AUTH_SCOPE_DENIED

API clientに、エンドポイントが要求する権限がありません。data.requiredScope に不足している権限が示されます。

Developer Consoleでその権限を追加し、変更を保存して、新しいトークンを取得してから再試行してください。権限（英語）を参照してください。

API clientを無効化または削除した後も、古いトークンは使えますか？

使えません。保護されたエンドポイントは、JWTの有効期限だけでなく、現在のAPI client・アプリケーション・アカウントの状態を検証します。

clientが無効化または削除された後は、新しいトークンを発行できず、既存のトークンも拒否されます。

clientSecret をWebサイトやモバイルアプリに保存できますか？

できません。clientSecret はサーバーの認証情報です。ブラウザのアセット、アプリケーションパッケージ、クライアントログでは確実に保護できません。

認証情報は自分が管理するサーバー上に保管してください。clientSecret、アクセストークン、WebSocketチケットをフロントエンドコード、公開リポジトリ、ログに書き込まないでください。

デバイスデータがおかしく見える

デバイス一覧にデバイスが表示されない

まず、そのデバイスが現在のアカウントに属していること、API clientがアクセスを許可されていることを確認してください。

デバイスがDeveloper Consoleには表示されるがAPIには表示されない場合は、デバイスの権限付与と device:read スコープを確認してください。原因が不明な場合は、サポートに連絡する前に requestId を記録してください。

デバイス一覧の状態が実機と今すぐ一致しない

デバイス一覧は、プラットフォームがすでに同期済みのデバイス状態を返します。一覧リクエストのたびに実機を能動的に更新するわけではなく、一覧表示、ダッシュボード、大量読み取りを目的としています。

ユーザーが明示的に更新する場合や、操作の前後の確認には、デバイスの取得（英語）またはWebSocketのステータスリクエストを使用してください。

周辺機器・オフライン・電源状態を確認するためにHTTPを頻繁にポーリングできますか？

推奨されません。周辺機器の状態、オフライン状態、電源イベントはリアルタイム志向のデータです。過度なHTTPポーリングはデバイスの更新負荷を増やし、レート制限に達しやすくなります。

推奨されるアプローチ:

1. デバイス一覧、ダッシュボード、バックグラウンド同期にはデバイス一覧の取得（英語）を使用します。
2. ユーザーが1台のデバイス詳細ページを明示的に更新する場合は、デバイスの取得（英語）またはWebSocketの device.state.get を使用します。
3. オフライン・電源・周辺機器状態の変化を継続的に監視するにはWebSocketイベントを使い、再接続後はHTTPまたは device.state.get で重要な状態を改めて確認します。

すべてのデバイスに対して数秒おきにリアルタイム更新エンドポイントを呼び出さないでください。イベント配信の欠落がないことは保証されておらず、同じアカウントの他の通常のリクエストに影響する可能性があります。

deviceType が UNSUPPORTED になっている

プラットフォームがそのデバイスに対して利用可能なデバイスタイプ定義をまだ提供していません。デバイスはアカウントに属し続けている可能性がありますが、クライアントはその状態スキーマや制御機能が利用可能だと想定してはいけません。

デバイスIDのプレフィックスから機能を推測しないでください。

デバイスがある操作に対応しているかどうかはどうすればわかりますか？

デバイスタイプ定義一覧の取得（英語）を確認し、capabilities.supportedOperations を調べてください。

一覧に含まれる操作のみを表示または呼び出すべきです。たとえば、device.rs485.transceive が存在しない限り、RS485透過送信を表示しないでください。

デバイス操作が期待どおりに完了しない

レスポンスは COMMAND_ACCEPTED だが、デバイスが動いていない

COMMAND_ACCEPTED は、プラットフォームがリクエストを受け付けたことを意味します。デバイスが操作を完了したことを意味するものではありません。

コマンドのステータスを確認してください。SUCCESS はデバイスが操作を確認したことを、TIMEOUT は最終確認が時間内に届かなかったことを意味します。以前のコマンド状態を復旧する際はコマンド結果の取得（英語）を使用してください。

コマンドが TIMEOUT の場合、デバイスは確実に実行しなかったのですか？

そうとは限りません。デバイスがコマンドを受信していなかった可能性、または確認が遅延・喪失している間に実行を完了していた可能性があります。

コマンドを盲目的に繰り返さないでください。特に複製すると危険な操作については、まず現在のデバイス状態を読み取ってください。

レスポンスコードが COMMAND_REJECTED

まず次の2点を確認してください。

1. デバイスタイプ定義にリクエストした操作が含まれている。
2. パラメータが有効なリレーインデックスなど、デバイスの機能に一致している。

両方とも正しい場合は、デバイスの接続状態と背後のデバイスパスを確認してください。

再試行では新しい Idempotency-Key を使うべきですか？

ネットワーク障害後に同じビジネス操作を再試行する場合は、元のキーを再利用してください。異なるデバイス、目標状態、ビジネス操作には、それぞれ異なるキーが必要です。

すべてのリクエストに1つの固定キーを使わないでください。HTTPの挙動（英語）を参照してください。

リアルタイム接続が不安定

WebSocketが接続を確立できない

アクセストークンが有効であることを確認し、新しい wsTicket を作成してください。チケットは短命かつ一度限りの使用であり、キャッシュしたり再利用したりしてはいけません。

WebSocketチケットの作成（英語）、続いて接続の確立（英語）を確認してください。

切断後、クライアントはどのように復旧すべきですか？

バックオフを使って再接続し、新しい接続ごとに新しいチケットを作成してください。再接続後は、切断中のイベントが完全に再送されると想定せず、必要な状態を再読み込みしてください。

ハートビートと再接続（英語）を参照してください。

イベントが重複する、または一部のイベントが欠落しているように見える

イベント処理は冪等でなければなりません。WebSocketはクライアントに変化を通知するものであり、唯一の永続的な状態のソースにしてはいけません。

ページの再読み込み、再接続、状態のギャップの検出があった後は、REST APIまたはWebSocketのステータスリクエストで状態を照会し、新しいベースラインを確立してください。

リクエストが制限されている、またはサービスが一時的に利用できない

レスポンスがHTTP 429

即座の再試行を止めてください。Retry-After を読み取り、許可された時間の後に再試行してください。サービスインスタンス間でバックオフを調整し、同期した再試行の集中を避けてください。

リアルタイム更新とデバイス制御は、スナップショット照会よりも厳しく制限されています。レート制限とリトライ（英語）を参照してください。

レスポンスが503または GATEWAY_UNAVAILABLE

デバイスへのリアルタイム経路が一時的に利用できません。requestId を記録し、バックオフを使って限られた回数だけ再試行してください。

状態が続く場合は再試行を止め、サポート向けにトラブルシューティングの詳細を準備してください。

トラブルシューティングの詳細を準備する

問題が解決しない場合は、次の情報を収集してください。

情報	例または補足
requestId	APIレスポンスに含まれるリクエストのトレースID
APIクライアントID	clientSecret は絶対に含めないでください
リクエストのメソッドとパス	GET /wlte/v1/devices
UTCでのタイムスタンプ	問題が発生した正確な時刻
HTTPステータスとビジネス code	例: 403 / AUTH_SCOPE_DENIED
サニタイズ済みのパラメータ	パスワード、トークン、個人情報を除去したもの

その後、サポートに連絡から問題を報告してください。