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 の戻り値に合わせて別の形式で取得することもできます。