トリガーの管理

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

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

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

トリガーの削除

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

let triggerID = trigger.triggerID

// Delete a trigger.
api.deleteTrigger(triggerID) { (triggerID: string!, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
}

トリガーを削除するには、トリガー ID を取得する必要があります。トリガー ID は、Trigger の triggerID で取得できます。

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

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

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

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

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

let triggerID = trigger.triggerID

// Disable a trigger.
api.enableTrigger(triggerID, enable: false) { (trigger: Trigger?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
}

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

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

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

トリガーの更新

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

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

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

// Get a trigger to update.
var triggerOrg: Trigger
// triggerOrg = ...

// Create a command form from the existing trigger.
let form = TriggeredCommandForm(command: triggerOrg.command!);

// Create a new predicate.
let condition = Condition(clause:RangeClause(field: "currentTemperature", lowerLimitInt: 28, lowerIncluded: true))
let predicate = StatePredicate(condition: condition, triggersWhen: TriggersWhen.CONDITION_FALSE_TO_TRUE)

// Set a new description.
let options = TriggerOptions(triggerDescription: "Power on when the temperature goes over 28 deg C")

// Patch the existing trigger.
let triggerID = triggerOrg.triggerID
api.patchTrigger(triggerID, form: form, predicate: predicate, options: options) { (updatedTrigger: Trigger?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
}

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

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

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

• triggerOrg.command から TriggeredCommandForm を作成します。この例では triggerOrg.command の内容を変更せずに patchTrigger に渡していますが、変更する場合は、イニシャライザーの変更したいパラメーターに新しい値を指定して TriggeredCommandForm を作成します。指定方法については、詳細情報を指定したトリガーの登録例 を参照してください。

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

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

• triggerOrg から TriggerOptions を作成します。このとき、triggerDescription に新しい説明を指定します。指定方法については、詳細情報を指定したトリガーの登録例 を参照してください。

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

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

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

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

トリガーの取得

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

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

let triggerID = "_trigger_id_"

// Get a trigger.
api.getTrigger(triggerID) { (trigger: Trigger?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
}

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

トリガーを取得するには、トリガー ID を取得する必要があります。トリガー ID は、Trigger の triggerID で取得できます。

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

トリガー一覧の取得

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

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

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

// Get a list of triggers.
api.listTriggers(nil, paginationKey: nil) { (triggers: [Trigger]?, paginationKey: String?, error :ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }

  // Do something with each trigger.
  for trigger in triggers! {
    let triggerCommand = trigger.command
    let triggerPredicate = trigger.predicate
  }

  // If the next page exists
  if paginationKey != nil {
    // Get the next page of the list.
    api.listTriggers(nil, paginationKey: paginationKey) { (triggers: [Trigger]?, paginationKey: String?, error :ThingIFError?) -> Void in
      if error != nil {
        // Handle the error.
        return
      }

      // Do something with each trigger.
    }
  }
}

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

listTriggers メソッドの paginationKey パラメータによって、現在のページの状態を表します。初めに nil を指定して listTriggers メソッドを呼び出すと先頭ページが取得でき、さらに、コールバックの pageneationKey として次のページネーションキーが返されます。これを次の listTriggers のページネーションキーとして指定すると、そのページを取得できます。最終的に全件取得されると、コールバックの pagenationKey として nil が通知されます。

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

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