Server Hook（サーバートリガー起動）のパラメーター

ここでは、Server Code のエンドポイントが Server Hook（サーバートリガー起動）によって呼び出された際の関数のパラメーターを示します。

Server Code の書式 に示すように、エンドポイントは以下のような形式です。

// Synchronous function
function funcName(params, context) {
  // Your code comes here...
}

// Asynchronous function
function funcName(params, context, done) {
  // Your code comes here...
}
  • 関数名 funcName はエンドポイント名になります。Server Code をコマンドラインツールで登録する際、このエンドポイント名を用いて実行するトリガーと対象関数を関連付けます。

  • 第 1 引数 params は、Server Code の実行を引き起こしたトリガーに関するパラメータを取得できます。引き起こしたトリガーごとに、以下の情報を取得できます。

    • Bucket 関連トリガーパラメータとパラメータの取得方法：

      トリガーパラメータ パラメータの取得方法
      実行を引き起こした Bucket のスコープ params.objectScope.appID と params.objectScope.userID が値をもつ場合は "ユーザースコープ"
      params.objectScope.appID と params.objectScope.groupID が値をもつ場合は "グループスコープ"
      params.objectScope.appID と params.objectScope.thingID が値をもつ場合は "Thing スコープ"
      params.objectScope.appID のみが値をもつ場合は "アプリケーションスコープ"
      実行を引き起こした Bucket の ID params.bucketID
      実行を引き起こした Object の ID params.objectID
      実行を引き起こした Object の URI params.uri


      ここでは、Server Hook 設定ファイルで指定されたトリガーに基づいて、作成、削除、更新された Object の情報を取得できます。作成/更新時には、ID や URI から Object を作成して refresh することで、作成/更新後のキーと値のペアを取得できます（更新前/削除前のペアは取得できません）。

      params.uri に設定される値のフォーマットは、実体を引き起こした Object のスコープにより異なります:

      • アプリケーションスコープ：kiicloud://buckets/<bucketID>/objects/<objectID>
      • グループスコープ：kiicloud://groups/<groupID>/buckets/<bucketID>/objects/<objectID>
      • ユーザースコープ：kiicloud://users/<userID>/buckets/<bucketID>/objects/<objectID>
      • Thing スコープ：kiicloud://things/<thingID>/buckets/<bucketID>/objects/<objectID>

    • グループ関連トリガーパラメータとパラメータの取得方法：

      トリガーパラメータ パラメータの取得方法
      実行を引き起こしたグループの ID params.groupID
      実行を引き起こした Object の URI params.uri
      実行を引き起こした追加/削除済みユーザー 1 人の ID（トリガーがグループメンバーの追加/削除だった場合のみ通知、他のメンバーは含まない） params.members
      実行を引き起こされた際に、追加/削除に失敗したユーザー 1 人の ID（トリガーがグループメンバーの追加/削除だった場合のみ通知、他のメンバーは含まない） params.failed


      params.uri に設定される値のフォーマットは kiicloud://groups/<groupID> になります。

    • ユーザー関連トリガーパラメータとパラメータの取得方法：

      トリガーパラメータ パラメータの取得方法
      実行を引き起こしたユーザーの ID params.userID
      実行を引き起こしたユーザーの URI params.uri


      params.uri に設定される値のフォーマットは kiicloud://users/<userID> になります。

    • Thing 関連トリガーパラメータとパラメータの取得方法：

      トリガーパラメータ パラメータの取得方法
      実行を引き起こした Thing の ID params.thingID
      実行を引き起こした Thing の vendorThingID（トリガーが Thing の登録だった場合のみ通知） params.vendorThingID
      実行を引き起こした Thing の URI params.uri
      Thing オーナーとして追加または削除されたユーザーの ID（トリガーが Thing オーナーの登録または削除だった場合のみ通知） params.userID
      Thing オーナーとして追加または削除されたグループの ID（トリガーが Thing オーナーの登録または削除だった場合のみ通知） params.groupID
      更新されたフィールドとその値（トリガーが Thing 情報の更新だった場合のみ通知） params.values
      MQTT コネクションが正常切断したか異常切断したか。True の場合は正常切断、False の場合は異常切断（トリガーが Thing のオフライン化だった場合のみ通知） params.expected


      params.uri に設定される値のフォーマットは kiicloud://things/<thingID> になります。

      params.values には、追加または更新されたフィールドとその値が JSON 形式で渡されます。削除されたフィールドには null が記録されます。

      一例として、以下のように Thing 情報が更新された場合を考えます。

      • フィールド "_lot" が、"LOT_12345" という値とともに追加された。
      • フィールド "_firmwareVersion" の値が "updated_version" に更新された。
      • カスタムフィールド "custom_field_1" が、"new_value_1" という値とともに追加された。
      • カスタムフィールド "custom_field_2" の値が "updated_value_2" に更新された。
      • カスタムフィールド "custom_field_3" が削除された。

      この場合、param.values には以下の JSON データが渡されます。

      {
    "_lot": "LOT_12345",
    "_firmwareVersion": "updated_version",
    "custom_field_1": "new_value_1",
    "custom_field_2": "updated_value_2",
    "custom_field_3": null
}

    • Installation 関連トリガーパラメータとパラメータの取得方法：

      トリガーパラメータ パラメータの取得方法
      デバイスをインストール/アンインストールしたユーザーの ID（FCM、APNs） params.userID
      デバイスをインストール/アンインストールした Thing の ID（MQTT） params.thingID
      実行を引き起こしたデバイスインストール/アンインストールの ID（Installation ID の値で、Installation Registration ID ではない） params.installationID
      実行を引き起こしたデバイスインストール/アインインストールの URI params.uri


      params.uri に設定される値のフォーマットは kiicloud://installations/<installationID> になります。

  • 第 2 引数 context はアプリケーション関連パラメータ取得のために使用します。

    • getAppID メソッドを使うと AppID が取得できます。
    • getAppKey メソッドを使うと AppKey が取得できます。
    • getAccessToken メソッドを使うと、トリガーが実行される原因となったリクエストに指定されていたアクセストークンを取得できます。たとえば、Bucket 変更のトリガーでは、その Bucket を書き換えたユーザーのアクセストークンを取得できます。
      • ログイン処理 を実行することで、クライアントと同じユーザーの権限で Server Code を実行できます（サンプルは こちら）。
      • さらに、このメソッドを使うと、トリガーの対象がログイン済みユーザーから変更されたのか（有効なアクセストークンが返ります）、匿名ユーザーで変更されたのか（null が返ります）も判断できます。
    • getAppAdminContext メソッドを使うと アプリ管理者 のコンテキスト（KiiAppAdminContext）が取得できます。このコンテキストのメソッドからユーザーやグループの操作をアプリ管理者権限で実行できます（サンプルは こちら）。

  • 第 3 引数 done は 非同期的な実行の場合に、Server Code の実行を完了するためのコールバック関数です。コールバック関数への引数は特に意味を持ちません。詳細は 非同期的な実行 を参照してください。

サーバートリガー起動では、Server Code からの戻り値は特に意味を持たないため、同期的な実行での return ステートメントの戻り値や、done への引数値は無視されます。

実行形態の判別

エンドポイントが呼び出された際、サーバートリガー起動による起動かどうかを context.isInvokedByHook() によって調べることができます。このメソッドは、サーバートリガーで起動された場合だけ true を返します。

呼び出し方法 context.isInvokedByHook() の戻り値
手動実行 false
Server Hook（サーバートリガー起動） true
Server Hook（スケジュール起動） false
Thing-IF のトリガー起動 false

サーバートリガーとして登録されたエンドポイントが手動実行などで不正に呼び出された場合、エラー応答する用途などに利用できます。

function myFunction(params, context, done) {
  if (!context.isInvokedByHook()) {
    done("ERROR: The endpoint can only call by server triggers.");
    return;
  }
  // Do somethig.
  done("SUCCESS");
}