コマンドを実行するトリガー

コマンドを自動実行する場合、実行するコマンドのテンプレートと実行条件をトリガーに設定します。

トリガーの定義

トリガーの定義は、以下のフィールドを使ってリクエストボディーに記述します。

フィールド 必須項目か？ 説明
triggersWhat ◯ トリガーが実行する対象。コマンドを実行する場合は "COMMAND" を指定します。
predicate ◯ トリガー実行条件。定義方法については トリガーの実行条件 を参照してください。
command ◯ トリガー実行条件が満たされた際に実行するコマンド。定義方法については下記の表を参照してください。
title トリガーのタイトル（最大 50 文字まで）
description トリガーの説明（最大 200 文字まで）
metadata トリガーのメタデータ（JSONObject 形式）

command 内は次のように定義します。

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

トリガーの登録に成功すると、Thing Interaction Framework は triggerID を払い出します。triggerID は次のように 201 応答として返されます。

HTTP/1.1 201 Created
Content-Type: application/json
{
  "triggerID": "{TRIGGER_ID}"
}

時間条件（単発）のトリガーの登録

単発の時間条件を持つトリガーの登録例を以下に挙げます。

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}/triggers" \
  -d '{
    "triggersWhat": "COMMAND",
    "predicate": {
      "eventSource": "SCHEDULE_ONCE",
      "scheduleAt": 1483150970386
    },
    "command": {
      "schema": "SmartLight",
      "schemaVersion": 1,
      "issuer": "user:{USER_ID}",
      "actions": [
        {"setLightColor": {"lightColor": "333"}}
      ]
    },
    "title": "Example #1",
    "description": "Execute the command at the designated time",
    "metadata": {
      "color": "red",
      "hex": "#333"
    }
  }'

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

時間条件（繰り返し）のトリガーの登録

繰り返しの時間条件を持つトリガーの登録例を以下に挙げます。

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}/triggers" \
  -d '{
    "triggersWhat": "COMMAND",
    "predicate": {
      "eventSource": "SCHEDULE",
      "schedule": "0 9 * * *"
    },
    "command": {
      "schema": "SmartLight",
      "schemaVersion": 1,
      "issuer": "user:{USER_ID}",
      "actions": [
        {"setLightColor": {"lightColor": "333"}}
      ]
    },
    "title": "Example #2",
    "description": "Execute the command on the scheduled interval",
    "metadata": {
      "color": "red",
      "hex": "#333"
    }
  }'

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

実行時間の設定方法については、時間条件（繰り返し） を参照してください。

ステート条件のトリガーの登録

ステート条件を持つトリガーの登録例を以下に挙げます。

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}/triggers" \
  -d '{
    "triggersWhat": "COMMAND",
    "predicate": {
      "eventSource": "STATES",
      "condition": {"type": "eq", "field": "power", "value": true},
      "triggersWhen": "CONDITION_CHANGED"
    },
    "command": {
      "schema": "SmartLight",
      "schemaVersion": 1,
      "issuer": "user:{USER_ID}",
      "target": "thing:{TARGET_THING_ID}",
      "actions": [
        {"setLightColor": {"lightColor": "333"}}
      ]
    },
    "title": "Example #3",
    "description": "Execute the command when the state condition is met",
    "metadata": {
      "color": "red",
      "hex": "#333"
    }
  }'

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