トリガーの実行条件

トリガーには、実行条件と、条件が満たされた場合に実行するコマンドまたは Server Code を登録します。以下の 3 種類の実行条件が指定可能です。

  • 時間条件（単発）
  • 時間条件（繰り返し）
  • ステート条件

時間条件（単発）

指定した時間にトリガーを一度だけ実行する条件です。

時間条件を指定する場合は ScheduleOncePredicate クラスを使用します。

トリガーを実行する時間は scheduleAt に指定します。指定は UNIX 時間（ミリ秒、UTC）で行ってください。

時間条件（繰り返し）

指定した時間にトリガーを繰り返し実行する条件です。

繰り返しの時間条件を指定する場合は SchedulePredicate クラスを使用します。

トリガーを実行する時間は cron 形式で指定します。

ステート条件

Thing のステートの最新フィールド値に基づいてトリガーの実行を判断する条件です。トリガーには、ステートとの比較条件と、トリガーの実行条件（比較条件がどのような状態の時にトリガーを実行するか）という 2 つの条件を設定します。

ステート条件を指定する場合は StatePredicate クラスを使用します。

ステート条件は、以下の 2 つの条件により定義されます。

比較条件

KiiClause クラスのサブクラスによって、ステートの最新のフィールド値との比較条件を指定します。クラス図 もご覧ください。

KiiClasuse のサブクラスでは、以下のメソッドを使用して条件を指定します。

メソッド 定義される比較条件
Equals コンストラクタ フィールドの値が、指定の値に等しい場合に true。
NotEquals コンストラクタ フィールドの値が、指定の値に等しくない場合に true。一旦 Equals オブジェクトを作成し、これを NotEquals に渡すことで「等しくない」を指定。
Range.range() フィールドの値が、指定された値の間に入っている場合に true。上限と下限それぞれの値を含むかどうかも指定可能。
Range.greaterThan() フィールドの値が、指定された値より大きい場合に true。
Range.greaterThanEquals() フィールドの値が、指定された値以上の場合に true。
Range.lessThan() フィールドの値が、指定された値より小さい場合に true。
Range.lessThanEquals() フィールドの値が、指定された値以下の場合に true。
And コンストラクタ 複数の条件を AND で結合。引数の KiiClause すべてが true の場合に true
Or コンストラクタ 複数の条件を OR で結合。引数の KiiClause のいずれか 1 つでも true の場合に true

条件を指定する際は、これらを組み合わせて 1 つの KiiClause インスタンスを作成します。

実行条件

比較条件で指定された KiiClause が、どのような状態の時にトリガーを実行するのかを指定します。以下の 3 通りのいずれかを指定できます。

値 実行条件
TriggersWhen.CONDITION_TRUE 比較条件が true のときに実行
TriggersWhen.CONDITION_FALSE_TO_TRUE 前回の比較条件が false で、今回が true のときに実行
TriggersWhen.CONDITION_CHANGED 前回と比較条件が変化しているときに実行

「比較条件が false の時に実行」または「前回の比較条件が true で、今回が false のときに実行」を指定したい場合は、比較条件全体が逆の論理になるように調整してください（new Equals(clause, false) でも実現できます）。

CONDITION_TRUE を使用する場合、ステートの登録ごとにコマンドや Server Code が実行される可能性を考慮してください。たとえば、「室温 30 度以上」の条件を CONDITION_TRUE で指定したときに 30 度以上の室温が続くと、ステートが更新されるたびに、毎回コマンドや Server Code が実行されます。

同一条件でトリガーの登録処理を何度も行うと、ステートの条件が満たされるたびに、それぞれのトリガーによるコマンドや Server Code が複数回実行されます。必要に応じて、トリガー一覧の取得 などの機能を使って重複登録を避けてください。