トリガーの実行条件

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

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

時間条件（単発）

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

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

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

時間条件（繰り返し）

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

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

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

ステート条件

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

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

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

比較条件

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

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

メソッド 定義される比較条件
EqualsClause イニシャライザ フィールドの値が、指定の値に等しい場合に true。
NotEqualsClause イニシャライザ フィールドの値が、指定の値に等しくない場合に true。一旦 EqualsClause オブジェクトを作成し、これを NotEqualsClause に渡すことで「等しくない」を指定。
RangeClause イニシャライザ（field:lowerLimit:lowerIncluded:
upperLimit:upperIncluded:）		 フィールドの値が、指定された値の間に入っている場合に true。上限と下限それぞれの値を含むかどうかも指定可能。
RangeClause イニシャライザ（field:upperLimit:upperIncluded） フィールドの値が、指定された値より小さい場合、または、指定された値以下の場合に true。
RangeClause イニシャライザ（field:lowerLimit:lowerIncluded） フィールドの値が、指定された値より大きい場合、または、指定された値以上の場合に true。
AndClause イニシャライザ 複数の条件を AND で結合。引数の Clause すべてが true の場合に true
OrClause イニシャライザ 複数の条件を OR で結合。引数の Clause のいずれか 1 つでも true の場合に true

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

実行条件

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

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

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

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

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