トリガーの管理

トリガーが登録されると、登録済みのトリガーについて以下の管理機能を利用できます。

• トリガーの削除
• トリガーの有効化と無効化
• トリガーの更新
• トリガーの取得
• トリガー一覧の取得

いずれも、Thing-IF SDK の初期化 に示す方法によって、初期登録済みの ThingIFAPI のインスタンス api を入手しておく必要があります。

トリガーの削除

トリガーを削除するサンプルコードを以下に示します。

String triggerID = trigger.getTriggerID();
try {
  // Delete a trigger.
  api.deleteTrigger(triggerID);
} catch (ThingIFException e) {
  // Handle the error.
}

トリガーを削除するには、トリガー ID を取得する必要があります。トリガー ID は、getTriggerID メソッドで取得できます。

Trigger のインスタンス trigger は、登録時や 一覧取得機能 によって取得できます。

トリガーの有効化と無効化

サーバーに登録したトリガーを有効化または無効化することができます。無効化したトリガーは、実行の対象外となります。

状態を切り替えるサンプルコードを以下に示します。

String triggerID = trigger.getTriggerID();
boolean enabled = false;
try {
  // Disable a trigger.
  api.enableTrigger(triggerID, enabled);
} catch (ThingIFException e) {
  // Handle the error.
}

ここでは、enabled を false に設定しているため、指定されたトリガーが無効化されます。有効化するには、enabled を true に設定します。

トリガーを有効化または無効化するには、トリガー ID を取得する必要があります。トリガー ID は、getTriggerID メソッドで取得できます。

Trigger のインスタンス trigger は、登録時や 一覧取得機能 によって取得できます。

トリガーの更新

登録済みのトリガーで実行する処理や実行条件を更新できます。

以下に 詳細情報を指定したトリガーの登録例 で登録したトリガーを更新するサンプルコードを示します。

ここでは、「温度計デバイスが 30 度以上になったとき、エアコンの電源を入れる」トリガーの実行条件を、「温度計デバイスが 28 度以上になったとき」に変更し、それに合わせてトリガーの説明も変更します。

// Get a trigger to update.
Trigger triggerOrg;
// triggerOrg = ...

// Create a command form from the existing trigger.
TriggeredCommandForm.Builder cb = TriggeredCommandForm.Builder.newBuilderFromCommand(triggerOrg.getCommand());
TriggeredCommandForm form = cb.build();

// Create a new predicate.
Condition condition = new Condition(Range.greaterThanEquals("currentTemperature", 28));
StatePredicate predicate = new StatePredicate(condition, TriggersWhen.CONDITION_FALSE_TO_TRUE);

// Create new trigger options from the existing title and metadata and a new description.
TriggerOptions.Builder ob = TriggerOptions.Builder.newBuilder();
ob.setTitle(triggerOrg.getTitle());
ob.setMetadata(triggerOrg.getMetadata());
ob.setDescription("Power on when the temperature goes over 28 deg C");
TriggerOptions options = ob.build();

try {
  // Patch the existing trigger.
  String triggerID = triggerOrg.getTriggerID();
  Trigger updatedTrigger = api.patchTrigger(triggerID, form, predicate, options);
} catch (ThingIFException e) {
  // Handle the error.
}

トリガーを更新するには、更新するトリガーを取得し、トリガーを構成する TriggeredCommandForm（コマンド）または ServerCode（Server Code）、StatePredicate（実行条件）、および TriggerOptions（トリガーの詳細情報）を個別に更新してから、それらを引数にして patchTrigger を実行します。更新前のトリガーの内容を複製して変更する箇所のみを上書きすることによって、新しいコマンドやトリガーの詳細情報を作成します。

ここでは、次の処理を行っています。

• 更新するトリガーを triggerOrg に取得します。Trigger のインスタンスは、登録時や 一覧取得機能 によって取得できます。

• TriggeredCommandForm.Builder で triggerOrg のコマンドから、トリガー更新用のコマンドを作成します。この例では元のコマンドの内容を変更せずに patchTrigger に渡していますが、変更する場合は、そのフィールドに新しい値を指定してから build メソッドで TriggeredCommandForm を作成します。指定方法については、詳細情報を指定したトリガーの登録例 を参照してください。

  Server Code を実行するトリガーの Server Code を更新する場合は、新しいエンドポイントの情報を ServerCode として作成します。指定方法については、Server Code を実行するトリガー を参照してください。

• 新しい実行条件を StatePredicate として作成します。実行条件の指定方法については、トリガーの実行条件 を参照してください。

• TriggerOptions.Builder で triggerOrg のトリガー詳細情報から、トリガー更新用の詳細情報を作成します。setTitle メソッドと setMetadata メソッドで元のタイトルとメタデータを設定し、setDescription メソッドで新しい説明を設定します。設定後、build メソッドで TriggerOptions を作成します。指定方法については、詳細情報を指定したトリガーの登録例 を参照してください。

• triggerID、作成した TriggeredCommandForm、StatePredicate、および TriggerOptions を patchTrigger メソッドに指定して、ThingIFAPI のインスタンス api（温度計デバイス）のトリガーを更新します。

• トリガーの更新に成功すると、updatedTrigger に更新されたトリガーが返されます。

patchTrigger メソッドでは、TriggeredCommandForm、StatePredicate の単位でトリガーの設定値を更新することができます。null を指定した場合、その要素は更新されません。たとえば、上のサンプルコードで TriggeredCommandForm に null を設定しても同じ結果になります。TriggerOptions の各フィールドは設定した値のみが更新されます。null を指定した値は更新されません。

TriggeredCommandForm の targetID に null を指定すると、トリガーの登録されている Thing がコマンドを実行する Thing として設定されます。この例のように、更新前のトリガーで、トリガーの登録先 Thing（温度計デバイス）と異なる Thing（エアコン）でコマンドを実行するように指定していた場合は注意してください。

トリガーの取得

トリガーを取得できます。

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

String triggerID = "_trigger_id_";

try {
  // Get a trigger.
  Trigger trigger = api.getTrigger(triggerID);
} catch (ThingIFException e) {
  // Handle the error.
}

トリガーの取得に成功すると、trigger に取得されたトリガーが返されます。

トリガーを取得するには、トリガー ID を取得する必要があります。トリガー ID は、getTriggerID メソッドで取得できます。

Trigger のインスタンス trigger は、登録時や 一覧取得機能 によっても取得できます。

トリガー一覧の取得

サーバーに登録されているトリガーを全件取得できます。

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

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

try {
  String paginationKey = null;

  do {
    // Get a list of triggers.
    Pair<List<Trigger>, String> results = api.listTriggers(0, paginationKey);
    List<Trigger> triggers = results.first;

    // Do something with each trigger.
    for (Trigger trigger : triggers) {
      Command triggerCommand = trigger.getCommand();
      StatePredicate triggerPredicate = (StatePredicate)trigger.getPredicate();
    }

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

listTriggers メソッドによってサーバーに登録されたトリガーを一覧取得しています。

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

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

results.first に取得できたトリガーの一覧が入っています。トリガー中のコマンドや条件を取得することができます。