トリガーの管理

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

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

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

トリガーの削除

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

const triggerID = trigger.triggerID;

// Delete a trigger.
api.deleteTrigger(triggerID).then((triggerID: string) => {
  // Do something.
}).catch((error: ThingIF.ThingIFError) => {
  // Handle the error.
});

var triggerID = trigger.triggerID;

// Delete a trigger.
api.deleteTrigger(triggerID).then(
  function(triggerID) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
  }
);

トリガーを削除するには、トリガー ID を取得する必要があります。トリガー ID は、Trigger クラスの triggerID プロパティで取得できます。

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

削除に成功するとトリガー ID が返されます。

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

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

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

const triggerID = trigger.triggerID;

// Disable a trigger.
api.enableTrigger(triggerID, false).then((trigger: ThingIF.Trigger) => {
  // Do something.
}).catch((error: ThingIF.ThingIFError) => {
  // Handle the error.
});

var triggerID = trigger.triggerID;

// Disable a trigger.
api.enableTrigger(triggerID, false).then(
  function(trigger) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
  }
);

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

トリガーを有効化または無効化するには、トリガー ID を取得する必要があります。トリガー ID は、Trigger の triggerID プロパティで取得できます。

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

トリガーの取得

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

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

const triggerID = "_trigger_id_";

// Get a trigger to update.
api.getTrigger(triggerID).then((trigger: ThingIF.Trigger) => {
  // Do something.
}).catch((error: ThingIF.ThingIFError) => {
  // Handle the error.
});

var triggerID = "_trigger_id_";

// Get a trigger to update.
api.getTrigger(triggerID).then(
  function(trigger) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
  }
);

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

トリガーを取得するには、トリガー ID を取得する必要があります。トリガー ID は、triggerID プロパティで取得できます。

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

トリガーの更新

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

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

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

// Get a trigger to update.
let triggerOrg: ThingIF.Trigger;
// triggerOrg = ...

// Create a command from the existing trigger.
const commandOrg = triggerOrg.command;
const command = new ThingIF.TriggerCommandObject(
                  commandOrg.schema, commandOrg.schemaVersion, commandOrg.actions,
                  commandOrg.targetID, commandOrg.issuerID,
                  commandOrg.title, commandOrg.description, commandOrg.metadata);

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

// Set a new description.
const description = "Power on when the temperature goes over 28 deg C";

// Create a new trigger request.
const triggerRequest = new ThingIF.PatchCommandTriggerRequest(command, predicate, triggerOrg.triggerTitle, description, triggerOrg.metadata);

// Patch the existing trigger.
api.patchCommandTrigger(triggerOrg.triggerID, triggerRequest).then((updatedTrigger: ThingIF.Trigger) => {
  // Do something.
}).catch((error: ThingIF.ThingIFError) => {
  // Handle the error.
});

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

// Create a command from the existing trigger.
var commandOrg = triggerOrg.command;
var command = new ThingIF.TriggerCommandObject(
                  commandOrg.schema, commandOrg.schemaVersion, commandOrg.actions,
                  commandOrg.targetID, commandOrg.issuerID,
                  commandOrg.title, commandOrg.description, commandOrg.metadata);

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

// Set a new description.
var description = "Power on when the temperature goes over 28 deg C";

// Create a new trigger request.
var triggerRequest = new ThingIF.PatchCommandTriggerRequest(command, predicate, triggerOrg.triggerTitle, description, triggerOrg.metadata);

// Patch the existing trigger.
api.patchCommandTrigger(triggerOrg.triggerID, triggerRequest).then(
  function(updatedTrigger) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
  }
);

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

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

更新するトリガーを triggerOrg に取得します。Trigger のインスタンスは、登録時や一覧取得機能によって取得できます。
TriggerCommandObject でトリガー更新用のコマンドを作成します。この例では元のコマンドの内容を変更せずにインスタンスを生成し、トリガーを更新しています。変更する場合は、コンストラクタへのパラメーターの一部を目的の値に修正します。パラメーターの指定方法については、詳細情報を指定したトリガーの登録例を参照してください。
新しい実行条件を StatePredicate として作成します。実行条件の指定方法については、トリガーの実行条件を参照してください。
PatchCommandTriggerRequest でトリガーの詳細情報を指定します。作成の際、triggerOrg に格納されているトリガーの詳細情報を取得し、第 3 引数以降のパラメーターに指定して新しい値を設定しています。ここでは、説明のみを変更します。
PatchCommandTriggerRequest を patchCommandTrigger メソッドに指定して、ThingIFAPI のインスタンス api（温度計デバイス）のトリガーを更新します。
トリガーの更新に成功すると、updatedTrigger に更新されたトリガーが返されます。

patchCommandTrigger メソッドでは、TriggerCommandObject、StatePredicate の単位でトリガーの設定値を更新することができます。null を指定した場合、その要素は更新されません。上のサンプルコードでは、TriggerCommandObject を更新しないため、PatchCommandTriggerRequest の第 1 引数に null を設定しても同じ結果になります。トリガーの詳細情報（タイトル、詳細な説明文、JSON 形式で表現された任意のメタ情報）の各フィールドは設定した値のみが更新されます。設定しなかった値は更新されません。

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

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

トリガー一覧の取得

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

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

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

const callback = (error: Error, results: ThingIF.QueryResult<ThingIF.Trigger>)=> {
  if (error) {
    // Handle the error.
    return;
  }

  // Do something with each trigger.
  for (const trigger of results.results) {
    const triggerCommand = trigger.command;
    const triggerPredicate = trigger.predicate;
  }

  // If the next page exists
  if (results.paginationKey) {
    // Get the next page of the list.
    api.listTriggers(new ThingIF.ListQueryOptions(null, results.paginationKey), callback);
  }
};

// Get a list of triggers.
api.listTriggers(new ThingIF.ListQueryOptions(10), callback);

var callback = function(error, results) {
  if (error) {
    // Handle the error.
    return;
  }

  // Do something with each trigger.
  for (var i = 0; i < results.results.length; i++) {
    var trigger = results.results[i];
    var triggerCommand = trigger.command;
    var triggerPredicate = trigger.predicate;
  }

  // If the next page exists
  if (results.paginationKey) {
    // Get the next page of the list.
    api.listTriggers(new ThingIF.ListQueryOptions(null, results.paginationKey), callback);
  }
};

// Get a list of triggers.
api.listTriggers(new ThingIF.ListQueryOptions(10), callback);

listTriggers メソッドによってサーバーに登録されたトリガーを一覧取得しています。このメソッドは Promise にも対応していますが、全件取得するには再帰によるループ構造を作成する必要があるため、コールバック関数によるサンプルコードとしています。Promise によってループを実現する方法は、KiiObject の検索の実装例などを参考にしてください。

listTriggers メソッドでは、ListQueryOptions の第 2 引数によって、現在のページの状態を表します。初めにページネーションキーの指定なしで listTriggers メソッドを呼び出すと先頭ページが取得できます。listTriggers メソッドのコールバックでトリガー一覧を取得した際、results.pagenationKey によって次のページネーションキーが返されます。これを次のページネーションキーとして指定すると、前回の続きのコマンドを取得できます。最終的に全件取得されると、コールバックの results.pagenationKey は undefined として通知されます。

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

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