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"