コマンドの実行

モバイルアプリからコマンドを送信して Thing を制御することができます。Thing 側は、コマンドリザルト（コマンド実行結果）を Thing Interaction Framework に返すことで、モバイルアプリなどよりコマンドリザルトが参照可能になります。

コマンドの概要についてはアクションとコマンドの実行をご参照ください。

REST API では以下の操作が行えます。

モバイルアプリ

コマンドの送信
コマンドリザルトの送信
コマンドリザルトの取得
登録済みコマンド一覧の取得

Thing

コマンドの受信
コマンドリザルトの送信

コマンドの送信

コマンドを送信する例を以下に挙げます。

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands" \
  -d '{
    "actions": [
      {"turnPower":{"power":true}},
      {"setPresetTemperature":{"presetTemperature":25}},
      {"setFanSpeed":{"fanSpeed":5}}
    ],
    "issuer": "user:{USER_ID}",
    "schema": "SmartLight",
    "schemaVersion": 1,
    "title": "AirConditioner-Demo",
    "description": "Set the air conditioner to my favorite settings",
    "metadata": {"created_at":"20150901"}
  }'

Thing オーナーのアクセストークンを指定してください。また {THING_ID} を対象となる Thing の thingID に差し替えてください。

コマンドは次のように定義します。

フィールド	必須項目か？	説明
`actions`	◯	コマンドで送信するアクションの配列。上記の例では 3 つのアクション（`turnPower`、`setPresetTemperature`、`setFanSpeed`）がコマンドとして送信されています。また例示されているように、各アクションに対してパラメーターを設定できます。
`issuer`	◯	コマンド発行者。対象となる Thing のオーナーである必要があります。ユーザー ID かグループ ID のいずれかが指定可能です。ユーザー ID の場合は user:、グループ ID の場合は group: をプレフィックスとしてつけてください。
`schema`、`schemaVersion`	◯	スキーマ名とバージョン。スキーマバージョンの不一致を検出するための情報です（詳細はこちらをご覧ください）。
`title`		コマンドのタイトル（最大 50 文字まで）。
`description`		コマンドの説明（最大 200 文字まで）。
`metadata`		コマンドのメタデータ（JSONObject 形式）

コマンドの登録が成功すると、Thing Interaction Framework は commandID を払い出します。commandID は以下のように 201 応答として返されます。

HTTP/1.1 201 Created
Content-Type: application/json
{
  "commandID":"{COMMAND_ID}"
}

commandID は、コマンドリザルトの送信および取得を行う際に利用します。

コマンドリザルトの送信

コマンドの実行が完了すると、Thing は Thing Interaction Framework にコマンドリザルトを送信します。コマンドリザルトには、アクションリザルト（各アクションの実行結果）をまとめます。

コマンドリザルトを送信する例を以下にあげます。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands/{COMMAND_ID}/action-results" \
  -d '{
    "actionResults": [
      {"turnPower": {"succeeded": true}},
      {"setPresetTemperature": {"succeeded": true}},
      {"setFanSpeed": {"succeeded": false, "errorMessage": "Interuppted by user."}}
    ]
  }'

Thing のアクセストークンを指定してください。また {THING_ID} と {COMMAND_ID} を、対象となる Thing の thingID とコマンドの commandID にそれぞれ差し替えてください。

アクションリザルトは actionResults フィールド内に配列としてまとめます。上記の例のように、各アクションの実行結果を設定してください。アクションの実行に成功した場合は succeeded フィールドを true に、失敗した場合は false に設定します。実行に失敗した場合は、失敗理由等を errorMessage フィールドに記載できます。

コマンドリザルトのアップロードが成功すると、Thing Interaction Framework は 204 応答を返します。

コマンドリザルトの取得

概要で図示したように、Thing Interaction Framework はコマンドリザルト（アクションリザルトのセット）を元のコマンドと一緒に管理します。

コマンドリザルトを取得するには、以下の例のように対象となるコマンドの commandID を指定して Thing Interaction Framework よりコマンドを取得します。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands/{COMMAND_ID}"

Thing または Thing オーナーのアクセストークンを指定してください。また {THING_ID} と {COMMAND_ID} を、対象となる Thing の thingID とコマンドの commandID にそれぞれ差し替えてください。

コマンドは、以下のように 200 応答として返されます。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "commandID": "{COMMAND_ID}",
  "commandState": "IMCOMPLETE",
  "schema": "SmartLight",
  "schemaVersion": 1,
  "target": "thing:{THING_ID}",
  "issuer": "user:{USER_ID}",
  "actionResults": [
    {"turnPower": {"succeeded": true}},
    {"setPresetTemperature": {"succeeded": true}},
    {"setFanSpeed": {"succeeded": false, "errorMessage": "Interuppted by user."}}
  ],
  "actions": [
    {"turnPower": {"power": true}},
    {"setPresetTemperature": {"presetTemperature": 25}},
    {"setFanSpeed": {"fanSpeed": 25}}
  ],
  "title": "AirConditioner-Demo",
  "description": "Set the air conditioner to my favorite settings",
  "metadata": {
    "created_at": "20150901"
  },
  "createdAt": 1450147577076,
  "modifiedAt": 1450149727923
}

アクションリザルトの配列は actionResults フィールドに格納されています。

また commandState フィールドには、コマンドリザルト全体としての結果（状態）が格納されています。

SENDING：コマンドは Thing Interaction Framework に登録され、Thing に送信中。
SEND_FAILED：コマンドは Thing Interaction Framework に登録されたが、Thing へのコマンド送信は失敗。
DONE：コマンド内の全てのアクション実行に成功。
INCOMPLETE：コマンド内の少なくとも 1 つのアクション実行に失敗。

登録済みコマンド一覧の取得

Thing Interaction Framework に登録済みの全てのコマンドを取得する例を以下に挙げます。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands"

コマンド一覧は、以下のように 200 応答として返されます。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "commands": [
    {
      "commandID": "{COMMAND_ID}",
      "schema": "SmartLight",
      "schemaVersion": 1,
      "target": "thing:{THING_ID}",
      "commandState": "INCOMPLETE",
      "issuer": "user:{USER_ID}",
      "actionResults": [
        {"turnPower": {"succeeded": true}},
        {"setPresetTemperature": {"succeeded": true}},
        {"setFanSpeed": {"errorMessage": "Interuppted by user.", "succeeded": false}}
      ],
      "actions": [
        {"turnPower": {"power": true}},
        {"setPresetTemperature": {"presetTemperature": 25}},
        {"setFanSpeed": {"fanSpeed": 25}}
      ],
      "title": "AirConditioner-Demo",
      "description": "Set the air conditioner to my favorite settings",
      "metadata": {
        "created_at": "20150901"
      },
      "createdAt": 1450147577076,
      "modifiedAt": 1450149727923
    },
    {
      "commandID": "{COMMAND_ID}",

      ... the command detail follows ...
    }
  ]
}

上の例のように、commands フィールドにコマンドの配列が格納されます。

ページネーション

登録済みコマンドが多数存在する場合、1 回の応答で全てのコマンドを取得できない場合があります。このような場合、ページネーションキー paginationKey を使ってコマンドの取得を行います。

初回の取得では、通常どおり（"paginationKey" を指定せずに）GET コマンドを実行します。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands"

全てのコマンドを一度に返せない場合、Thing Interaction Framework はコマンドの一部とともに "nextPaginationKey" という値を返します。

    ... an array of commands ...

    }
  ],
  "nextPaginationKey":"XXXYYY"
}

この "nextPaginationKey" の値をクエリパラメータ－ paginationKey に指定して GET コマンドを再度実行すると、未取得のコマンドを受け取ることができます。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands?paginationKey=XXXYYY?bestEffortLimit=100"

上記の例のように bestEffortLimit を指定することで、一度に返されるコマンド数の上限を指定することもできます。

なお、"nextPaginationKey" はページ指定の文字列のように見えますが、独自の値を与えることはできず、常に直前の検索結果で返されたものを指定します。

取得の結果、さらに次の "nextPaginationKey" が返された場合は、同様にこの値を指定して次のコマンド一覧を取得します。取得結果に "nextPaginationKey" が含まれない場合は、全件の取得が完了したことを意味します。

コマンドの受信

モバイルアプリからのコマンドは、MQTT によるプッシュ通知で受信できます。サーバー側からの PUBLISH コマンドを受信したとき、その MQTT トピックとペイロードを調べます。

MQTT トピック

コマンドを受信したときの MQTT トピックは、MQTT ブローカーへの接続情報として取得し、SUBSCRIBE コマンドの実行時に指定した MQTT トピックです。つまり、コネクションの確立時（HTTPS、MQTT）に接続情報の "mqttTopic" として得られた MQTT トピック名と同じものなります。

PUBLISH コマンドは様々な目的で受信するため、サーバー側からの PUBLISH コマンドを受け取った際には、必ず MQTT トピック名をチェックするように実装してください。また、未知の MQTT トピック名を持つ PUBLISH コマンドは、将来の拡張のため無視するように実装してください。

ペイロード

受信した PUBLISH コマンドのペイロードには以下のような JSON 文字列が含まれています。これは、アプリ開発ガイド（Android、iOS）で使用したエアコンの例によるコマンドです。

{
  "actions": [
    {
      "turnPower": {
        "power": true
      }
    },
    {
      "setPresetTemperature": {
        "presetTemperature": 25
      }
    },
    {
      "setFanSpeed": {
        "fanSpeed": 5
      }
    }
  ],
  "commandID": "000b6010-28a1-11e6-8367-22000a84d49d",
  "issuer": "user:0f2968a00022-49eb-6e11-ba32-00f4d2cc",
  "schema": "AirConditioner-Demo",
  "schemaVersion": 1
}

各フィールドの意味は以下のとおりです。

フィールド	説明
`actions`	コマンドが含むアクションの詳細です。内容は送信したコマンドに依存します。
`commandID`	コマンドのIDです。
`issuer`	コマンドの発行元のアカウントです。この例ではコマンド送信時のオーナーユーザーの ID を表します。
`schema`	コマンドのスキーマです。モバイルアプリでコマンドを送信する際に指定したスキーマ名が保持されます。
`schemaVersion`	コマンドのスキーマバージョンです。モバイルアプリでコマンドを送信する際に指定したスキーマバージョンが保持されます。

コマンドリザルトの送信

コマンドリザルトを送信する例を以下に挙げます。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/commands/{COMMAND_ID}/action-results" \
  -d '{
    "actionResults": [
      {"turnPower": {"succeeded": true}},
      {"setPresetTemperature": {"succeeded": true}},
      {"setFanSpeed": {"succeeded": false, "errorMessage": "Interuppted by user."}}
    ]
  }'

コマンドリザルトのアップロードが成功すると、Thing Interaction Framework は 204 応答を返します。