本文へスキップ

JSONの共通ルール

すべてのサービスインターフェースはJSONを使用しています。このページでは、一般的なパターンについて説明します。

ポート​

ポートインターフェースバージョン
10001HTTP REST + WebSocket（シミュレーションチャネル）v3.1（現在）
10020WebSocket（イベントチャネル、読み取り専用）—
10000レガシー WebSocket（v3.0 — v4.0 で削除予定）v3.0

HTTPレスポンスエンベロープ​

すべてのHTTPレスポンスは、同じエンベロープを使用します：

成功（データを含む）：

{ "ok": true, "data": { … } }

成功（データなし、変更専用エンドポイント）：

{ "ok": true }

エラー：

{ "ok": false, "error": "reason string" }

使用中止となったエンドポイント：

{ "ok": true, "deprecation_warning": "This route is deprecated. Use …" }

HTTPステータスコード​

コード意味
200成功
400不正なリクエスト — 本文に誤りがある、セレクタが曖昧である、または必須フィールドが欠落しています
404デバイス、セッション、またはリソースが見つかりません
405許可されていないメソッド

WebSocketメッセージの形式​

メッセージはJSONオブジェクトです。最上位のキーはデバイスグループ名（inverse3, verse_grip, wireless_verse_grip）であり、セッションレベルのコマンド用のオプションとして session キーを使用できます。

クライアント → サービス（コマンド）：

{
  "session": { "configure": { … } },
  "inverse3": [
    { "device_id": "049D", "configure": { … }, "commands": { … } }
  ]
}

サービス → クライアント（状態）：

{
  "session_id": 7,
  "inverse3": [
    { "device_id": "049D", "config": { … }, "state": { … }, "status": { … } }
  ]
}

サービスから送信される最初のメッセージには config（全体のスナップショット）が含まれます。その後のメッセージには stateわあ statusのみが含まれます。ワークフロー全体は WebSocketプロトコルを参照してください。

コンテンツの種類​

本文を含むすべてのHTTPリクエストは Content-Type: application/jsonを送信する必要があります。 WebSocketメッセージは、常にプレーンテキストのJSONフレームです。

不明なキー​

不明なキーは黙って無視されます

本サービスは、現在認識されていないJSONキーをエラーを発生させることなく無視します。コマンドがまったく効果がないように見える場合は、サービスのログを確認し、APIリファレンスとフィールド名が一致しているかを確認してください。 この動作は今後のバージョンで変更される予定です（未知のキーが警告イベントを発生させるように変更されます）。