Server Code を実行するトリガー

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

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

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

トリガーの登録を行う前に、Server Code を設置しておきます。設置方法は、サーバー機能拡張リファレンスガイドをご覧ください。

Server Code を設置した後、呼び出したいエンドポイントの情報をトリガーに設定します。

ここでは、「室温が 30 度以上の時、Server Code の alertTemperature エンドポイントを、パラメータ {"caller":"trigger"} で実行する」というトリガーの登録例を示します。

// Specify an end point of server code.
let accessToken = KiiUser.currentUser().accessToken
let param : Dictionary = ["caller": "trigger"]
let serverCode = ServerCode(endpoint: "alertTemperature", executorAccessToken: accessToken, targetAppID: nil, parameters: param)

// Create a predicate.
// Execute the server code when the temperature is greater than or equal to 30 deg C.
let condition = Condition(clause:RangeClause(field: "currentTemperature", lowerLimit: 30, lowerIncluded: true))
let predicate = StatePredicate(condition: condition, triggersWhen: TriggersWhen.CONDITION_FALSE_TO_TRUE)

// Send a trigger.
api.postNewTrigger(serverCode, predicate: predicate, completionHandler: { (trigger: Trigger?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

ここでは、ServerCode インスタンスと StatePredicate インスタンスを作成し、postNewTrigger メソッドでトリガーの登録を行っています。

ServerCode インスタンスによって、Server Code の実行条件を指定します。ServerCode のコンストラクタには、以下のパラメータを指定できます。

第 1 引数：実行される Server Code のエンドポイント名（JavaScript の関数名）を指定します。
第 2 引数：Server Code を実行する際のアクセストークンを指定します。ここではオーナーユーザーのアクセストークンを指定しています。Server Code では、context.getAccessToken() によって、呼び出し元のアクセストークンを取得して、そのユーザーの権限で処理を実行できます。トリガーから起動された場合は、ここで指定したアクセストークンが取得されます。
第 3 引数：Server Code がある Kii Cloud アプリケーションの AppID を指定します。トリガーでは自分以外のアプリケーションにある Server Code を呼び出すことができます。nil を指定した場合は、api を初期化したのと同じアプリケーションの Server Code を呼び出します。
第 4 引数：エンドポイントに渡すパラメータを指定します。Server Code でのパラメータは JSON ですが、swift では Dictionary を使用します。パラメータが不要な場合は nil を指定します。

トリガー実行条件の初期化方法はコマンドの自動実行の場合と同じです。

トリガーを登録すると、completionHandler の引数として Trigger インスタンスを取得できます。

Server Code の実行結果の取得

Server Code の実行結果を取得することができます。トリガーを設定後、実行条件を満たすステートが登録されるごとに Server Code が実行され、その結果は Thing Interaction Framework 内に蓄積されていきます。この結果は API を通して取得することができます。

登録されている実行結果が多数ある場合は、ページネーションを利用します。たとえば、実行結果が 30 件登録されている場合、10 件をページとして、10 件ずつ 3 回に分けて取得することができます。

以下にサンプルコードを示します。

// Get a list of server code results.
api.listTriggeredServerCodeResults(trigger!.triggerID, bestEffortLimit: nil, paginationKey: nil) { (results: [TriggeredServerCodeResult]?, paginationKey: String?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }

  // Check if the server code succeeded or not and process each result.
  for serverCodeResult in results! {
    if serverCodeResult.succeeded {
      let returnedValue = serverCodeResult.getReturnedValueAsString();
      let executedAt = serverCodeResult.executedAt;
    } else {
      let errorMessage = serverCodeResult.error!.errorMessage;
      let executedAt = serverCodeResult.executedAt;
    }
  }

  // If the next page exists
  if paginationKey != nil {
    // Get the next page of the list.
    api.listTriggeredServerCodeResults(trigger!.triggerID, bestEffortLimit: nil, paginationKey: paginationKey) { (results: [TriggeredServerCodeResult]?, paginationKey: String?, error: ThingIFError?) -> Void in
    if error != nil {
      // Handle the error.
      return
    }

    // Check if the server code succeeded or not and process each result.
  }
}

listTriggeredServerCodeResults メソッドによってサーバーに登録された実行結果を一覧取得しています。取得の際には、Server Code を登録した際に取得した Trigger クラスのインスタンス trigger が持つトリガーの ID が必要です。

paginationKey によって、現在のページの状態を表します。初めに nil で listTriggeredServerCodeResults メソッドを呼び出すと、先頭ページが取得でき、ハンドラーの引数の paginationKey として次のページネーションキーが返されます。これを次の listTriggeredServerCodeResults のページネーションキーとして指定すると、そのページを取得できます。最終的に全件取得されると、ページネーションキーは nil を返します。

listTriggeredServerCodeResults の第 2 引数は 1 回に取得するトリガーの件数です。nil を指定すると、サーバー側での自動設定になります。ページのサイズは Best Effort のため、値を指定しても、一度に指定件数分を取得できないことがあります。取得できなかったトリガーは、次のページで取得できます。

ハンドラーの引数の results に取得できた実行結果の一覧が入っています。コード例にあるように、成功したかどうか、実行した日時、成功時はその実行結果、失敗時はエラーメッセージをそれぞれ取得することができます。ここでの実行結果は文字列で取得していますが、数値や JSON など、Server Code の戻り値に合わせて別の形式で取得することもできます。