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

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

トリガーの定義

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

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

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

フィールド 必須項目か? 説明
actions コマンドで送信するアクションの配列。コマンドの送信 の例では 3 つのアクション(turnPowersetPresetTemperaturesetFanSpeed)がコマンドとして送信されています。また例示されているように、各アクションに対してパラメーターを設定できます。
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 に差し替えてください。