Server Code を実行するトリガー

Server Code を自動実行する場合、実行する Server Code と実行条件をトリガーに設定します。

Server Code が実行された後、その実行結果(エラーの有無や戻り値)を取得することもできます。

トリガーの定義

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

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

Server Code の定義

トリガーの定義の serverCode フィールドは、その直下の階層にさらに以下の情報を定義します。

フィールド 必須項目か? 説明
endpoint 呼び出す Server Code のエンドポイント名
parameters エンドポイントへのパラメータ
tartgetAppID 呼び出す Server Code がトリガーが設定されたアプリケーションと異なる場合、このアプリケーションの AppID
executorAccessToken Server Code の実行元ユーザーを表すアクセストークン(targetAppID を指定した場合は必須)

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

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

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

Server Code を自動実行するトリガーの登録例を以下に挙げます。

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": "SERVER_CODE",
    "predicate": {
      "eventSource": "STATES",
      "condition": {"type": "eq", "field": "power", "value": true},
      "triggersWhen": "CONDITION_CHANGED"
    },
    "serverCode" : {
      "endpoint" : "saveColor",
      "parameters" : {
        "brightness" : 100,
        "color" : "#FFF"
      },
      "executorAccessToken" : "_kuslkq71LdiHcR0Ez91uIT2N-fUBRst3vMnWE3Ge8o"
    },
    "title": "Example #2",
    "description": "Execute the server code when the state condition is met",
    "metadata": {
      "color": "red",
      "hex": "#333"
    }
  }'

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

Server Code の実行結果の取得

トリガーによって Server Code の自動実行を設定し、ステートの更新によって実際に Server Code が実行された場合、その実行結果を REST API で取得できます。

実行結果を取得する例を以下に挙げます。

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}/results/server-code"

Thing または Thing オーナーのアクセストークンを指定してください。

{THING_ID} を、対象となる Thing の thingID に差し替えてください。また、{TRIGGER_ID} をトリガーの登録時に REST の戻り値で取得できたトリガー ID に差し替えてください。

指定したトリガーに対する Server Code の実行結果一覧は、以下のように 200 応答として返されます。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "triggerServerCodeResults" : [ {
    "succeeded" : true,
    "returnedValue" : "1456801769894",
    "executedAt" : 1456801769904
  }, {
    "succeeded" : true,
    "returnedValue" : "1456801784981",
    "executedAt" : 1456801784987
  }, {
    "succeeded" : false,
    "executedAt" : 1456802646413,
    "error" : {
      "errorMessage" : "Error found while executing the developer-defined code",
      "details" : {
        "errorCode" : "RUNTIME_ERROR",
        "message" : "Error in Server Code"
      }
    }
  } ],
  "nextPaginationKey" : "200/1"
}

Server Code の実行が成功したかどうかが succeeded で取得できます。成功時はエンドポイントの戻り値と実行日時(UTC、ミリ秒)が得られます。失敗時は実行日時とエラーの詳細情報が得られます。

トリガー一覧の取得 時と同様に、以下のように GET コマンドのパラメータとして "paginationKey" によるページネーションと、bestEffortLimit による結果数の上限を指定できます。指定方法や役割は、トリガー一覧の場合と同じです。

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}/results/server-code?paginationKey=XXXYYY&bestEffortLimit=100"