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.
String accessToken = KiiUser.getCurrentUser().getAccessToken();
JSONObject param = new JSONObject("{\"caller\":\"trigger\"}");
ServerCode serverCode = new ServerCode("alertTemperature", accessToken, null, param);

// Create a predicate.
// Execute the server code when the temperature is greater than or equal to 30 deg C.
Condition condition = new Condition(Range.greaterThanEquals("currentTemperature", 30));
StatePredicate predicate = new StatePredicate(condition, TriggersWhen.CONDITION_FALSE_TO_TRUE);

try {
  // Send a trigger.
  Trigger trigger = api.postNewTrigger(serverCode, predicate);
} catch (ThingIFException e) {
  // Handle the error.
}

ここでは、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 を呼び出すことができます。null を指定した場合は、api を初期化したのと同じアプリケーションの Server Code を呼び出します。
第 4 引数：エンドポイントに渡すパラメータを JSONObject で指定します。パラメータが不要な場合は null を指定します。

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

トリガーを登録すると、戻り値として Trigger インスタンスを取得できます。

Server Code の実行結果の取得

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

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

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

try {
  String paginationKey = null;

  do {
    // Get a list of server code results.
    Pair<List<TriggeredServerCodeResult>, String> results = api.listTriggeredServerCodeResults(trigger.getTriggerID(), 0, paginationKey);
    List<TriggeredServerCodeResult> serverCodeResults = results.first;

    for (TriggeredServerCodeResult serverCodeResult : serverCodeResults) {
      // Check if the server code succeeded or not and process each result.
      if (serverCodeResult.isSucceeded()) {
        String returnedValue = serverCodeResult.getReturnedValueAsString();
        Date executedAt = new Date(serverCodeResult.getExecutedAt());
      } else {
        String errorMessage = serverCodeResult.getError().getErrorMessage();
        Date executedAt = new Date(serverCodeResult.getExecutedAt());
      }
    }

    // Get the next pagination key.
    paginationKey = results.second;
  } while (paginationKey != null);
} catch (ThingIFException e) {
  // Handle the error.
}

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

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

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

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