トランザクション仕様
ここでは、CWS APIにおけるトランザクション仕様について説明します。
トランザクションの概要
CWS APIを使ってデバイスに対して操作を指示する際、一連の操作要求全体がひとつのトランザクションとして扱われます。
CWS APIを介してデバイスに処理が依頼されると、そのトランザクションの実行結果は、システム連携設定で指定されたWebhook URLへ通知（トランザクション結果通知）として送られます。
これにより、APIを呼び出した側のシステムは、デバイスでの処理が成功したか、失敗したかなどのステータスを知ることができます。
CWS APIでは、Webhook URLへの通知以外に、トランザクションの状態を参照できるAPIも用意しています。
トランザクションの状態遷移
CWS APIにおけるトランザクションの状態遷移は、次の通りです。
トランザクションはAPIが呼び出された際にcreatedされます。その後、CWSからデバイスに対してトランザクションが送付され、デバイスでの処理状況に応じてトランザクションのステータスが遷移します。
デバイスを管理するGUIを用意する場合、例えばデバイスのアップデート中のステータス表示などはこのトランザクションの状態遷移を元に設計をしてください。
トランザクションの再送
デバイスがオフラインの場合、CWS APIにデバイスに対する操作を指示すると、未完了のトランザクションがCWS APIに滞留します。
滞留したトランザクションは、デバイスがオンラインになった際、次の全ての条件に合致しているものが再送(再実行)されます。
- トランザクションの状態が未完了(
created,published,accepted) - 同一のオペレーションIDで最後に受け付けている
- ソフトウェアアップデート、ファームウェアアップデートの操作を受け付けている場合は、対象のパッケージやバージョンが異なると、同一のオペレーションIDでも別のトランザクションとして扱われます。
- トランザクションの再送回数が10回未満
上記の条件に一致しない未完了のトランザクションは、CWS APIにて破棄され、状態がcanceledとなります。
デバイスをディアクティベートするかデバイスの初期化の操作を受け付けている場合は、受け付け以前に発行されたトランザクションは全てcanceledとなります。
CWS APIでcanceledとするトランザクションは、トランザクション結果通知(トランザクションの破棄)で通知されます。
トランザクションが破棄された理由は、通知内のmessageに記載されます。
オペレーションIDとトランザクションの処理結果
CWS APIでは、デバイスに対する操作内容に応じて、一意のキー(オペレーションID)を付与しています。
オペレーションID(operationId)を参照すると、CWS APIからデバイスに対して指示した操作が特定できます。
オペレーションIDは、以下で参照が可能です。
トランザクションのデバイスでの処理結果は、オペレーションIDにより異なるキーで通知されます。
デバイスに対する操作とオペレーションID、処理結果が通知されるキーは、次の通りです。
「処理結果が通知されるキー」は、トランザクション結果通知と、トランザクションの情報を取得するのレスポンス transactionResultEvent に含まれます。
| デバイスに対する操作 | オペレーションID | 処理結果が通知されるキー |
|---|---|---|
| デバイスをアクティベートする | post-v1-applications-devices | result |
| デバイスをディアクティベートする | delete-v1-applications-devices | result |
| Apnの設定をする | put-v1-applications-devices-settings-apn | result |
| Wi-Fiを設定する | put-v1-applications-devices-settings-wifi | result |
| Bluetoothデバイス/ネットワークの一覧を取得する | get-v1-applications-connectivity-list | statusCode |
| Bluetooth/ネットワークのON/OFF状態を取得する | get-v1-applications-connectivity-state | statusCode |
| Bluetooth/ネットワークのON/OFF状態を変更する | put-v1-applications-connectivity-state | statusCode |
| Bluetooth/ネットワークの設定を初期化する | delete-v1-applications-connectivity-reset | statusCode |
| Bluetoothデバイスのペアリングを行う | post-v1-applications-bluetooth-device | statusCode |
| ペアリング済みBluetoothデバイスを接続/切断する | put-v1-applications-bluetooth-device | statusCode |
| Bluetoothデバイスのペアリングを解除する | delete-v1-applications-bluetooth-device | statusCode |
| ソフトウェアをすぐにアップデートさせる | put-v1-applications-devices-apps | result |
| ファームウェアをすぐにアップデートさせる | put-v1-applications-devices-firmware | result |
| デバイスの初期化 | put-v1-applications-devices-reset | result |
| デバイスのシャットダウン | put-v1-applications-devices-shutdown | result |
| デバイスの再起動 | put-v1-applications-devices-reboot | result |
| 言語設定をする | put-v1-applications-devices-settings-lang | result |
| LauncherAppへのKey設定 | put-v1-applications-devices-apps-launcher-keys | result |
| デバイスでコマンドを実行させる | put-v1-applications-devices-commands | success |
| ソフトウェアをアンインストールする | delete-v1-applications-devices-package | result |
transactionResult との対応
トランザクションの情報を取得するおよびトランザクションの一覧を取得するでは、処理結果キーの値から導出したトランザクションの結果を transactionResult として返却しています。
成否のみ確認する場合は、こちらのフィールドが便利です。
処理結果キーと transactionResult の算出ルールは、次の通りです。
| 処理結果キー | 値の型 | transactionResult が success となる条件 |
|---|---|---|
result | 文字列 | 値が "success" |
success | 真偽値 | 値が true |
statusCode | 整数 | 値が 2xx（200〜299） |