トリガーの管理

トリガーが登録されると、登録済みのトリガーについて以下の管理機能を利用できます。

トリガーの削除
トリガーの有効化と無効化
トリガーの更新
トリガーの取得
トリガー一覧の取得

トリガーの削除

トリガーを削除する例を以下に挙げます。

curl -v -X DELETE \
  -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}/triggers/{TRIGGER_ID}"

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

トリガーの削除に成功すると、Thing Interaction Framework は 204 応答を返します。

トリガーの有効化と無効化

無効化

トリガーは無効化できます。無効化すると、トリガーの条件が満たされてもコマンドは実行されません。

トリガーを無効化する例を以下に挙げます。

curl -v -X PUT \
  -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}/triggers/{TRIGGER_ID}/disable"

トリガーの無効化に成功すると、Thing Interaction Framework は 204 応答を返します。

有効化

無効化されたトリガーは再度有効化できます。有効化すると、トリガーの条件が満たされると再度コマンドが実行されるようになります。

トリガーを有効化する例を以下に挙げます。

curl -v -X PUT \
  -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}/triggers/{TRIGGER_ID}/enable"

トリガーの有効化に成功すると、Thing Interaction Framework は 204 応答を返します。

トリガーの更新

コマンドを自動実行するトリガーの更新例を以下に挙げます。

curl -v -X PATCH \
  -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/{TRIGGER_ID}" \
  -d '{
    "triggersWhat": "COMMAND",
    "predicate": {
      "eventSource": "STATES",
      "condition": {
        "type": "eq",
        "field": "power",
        "value": true
      },
      "triggersWhen": "CONDITION_FALSE_TO_TRUE"
    },
    "title": "Modified test title",
    "description": "Modified test description",
    "metadata": {
      "color": "red",
      "hex": "#333"
    }
  }'

トリガーの更新に成功すると、Thing Interaction Framework は 204 応答を返します。

Server Code を自動実行するトリガーも同様に更新できます。

トリガーの取得

トリガーを取得する例を以下に挙げます。

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}/triggers/{TRIGGER_ID}"

トリガーは以下のように 200 応答で返されます。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "triggersWhat": "COMMAND",
  "triggerID":"{TRIGGER_ID}",
  "predicate":{
    "eventSource":"STATES",
    "condition":{"field":"power", "type":"eq", "value":true},
    "triggersWhen":"CONDITION_CHANGED"
  },
  "command":{
    "schema":"SmartLight",
    "schemaVersion":1,
    "actions":[
      {"setLightColor": {"lightColor": "333"}}
    ],
    "issuer":"user:{USER_ID}",
    "target":"thing:{THIHG_ID}"
  },
  "title":"Test title",
  "description":"Test description",
  "disabled":false,
  "metadata":{
    "color":"red",
    "hex":"#333"
  }
}

現在トリガーが有効か無効かは disabled フィールドで確認できます。

トリガー一覧の取得

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}/triggers"

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

トリガー一覧は、以下のように 200 応答として返されます。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "triggers": [
    {
      "triggersWhat": "COMMAND",
      "triggerID": "{TRIGGER_ID}",
      "predicate": {
        "eventSource": "STATES",
        "condition": {"type": "eq", "field": "power", "value": true},
        "triggersWhen": "CONDITION_CHANGED"
      },
      "command": {
        "schema": "SmartLight",
        "schemaVersion": 1,
        "actions": [
          {"setLightColor": {"lightColor": "333"}}
        ],
        "target": "thing:th.350948a00022-2d68-5e11-232a-001e9c52",
        "issuer": "user:d3d808a00022-2e0a-5e11-132a-00e8a0d9 "
      },
      "title": "Modified test title",
      "description": "Modified test description",
      "disabled": false,
      "metadata": {
        "color": "red",
        "hex": "#333"
      }
    },
    {
      "triggersWhat": "COMMAND",
      "triggerID": "{TRIGGER_ID}",

      ... the trigger detail follows ...
    }
  ]
}

上の例のように、triggers フィールドにトリガーの配列が格納されます。

コマンドの自動実行を行うトリガーと、Server Code の自動実行を行うトリガーの両方が混在状態で取得できます。

ページネーション

登録済みトリガーが多数存在する場合、一回の応答で全てのトリガーを取得できない場合があります。このような場合、ページネーションキー 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}/triggers"

全てのトリガーを一度に返せない場合、Thing Interaction Framework はトリガーの一部とともに "nextPaginationKey" という値を返します。

    ... an array of triggers ...

    }
  ],
  "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}/triggers?paginationKey=XXXYYY?bestEffortLimit=100"

上記の例のように bestEffortLimit を指定することで、一度に返されるトリガー数の上限を指定することもできます。

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

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