Server Hook 設定ファイル

Server Hook 設定ファイルは、作成した Server Code のプログラムを起動するタイミングを設定したファイルです。設定ファイルを作成後、Server Code と一緒に設置を行います。

Server Hook で定義可能な起動タイミングには次の 2 種類があります(それぞれの機能については機能ガイドの Server Code の実行形態 をご覧ください)。

これらの設定は、1 つの JSON 形式のファイル上にまとめて記述します。Server Hook 設定ファイルの全体の例を以下に示します。後で詳細を示すように、このファイルでは、ユーザ作成、アプリケーションスコープの Bucket の作成と削除、毎時 0 分の定期実行、毎日 2:30(UTC:協定世界時)の定期実行の 5 つの実行を定義しています。

{
  "kiicloud://users": [
    {
      "when": "USER_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "userCreated"
    }
  ],
  "kiicloud://buckets/highScore": [
    {
      "when": "DATA_OBJECT_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "highScoreCreated"
    },
    {
      "when": "DATA_OBJECT_DELETED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "highScoreDeleted"
    }
  ],
  "kiicloud://scheduler": {
    "HourlyCheck": {
      "what": "EXECUTE_SERVER_CODE",
      "cron": "0 * * * *",
      "endpoint": "checkData",
      "parameters": {
        "executionType": "hourly",
        "target": "user"
      }
    },
    "DailyCheck": {
      "what": "EXECUTE_SERVER_CODE",
      "cron": "30 2 * * *",
      "endpoint": "checkData",
      "parameters": {
        "executionType": "daily",
        "target": "all"
      }
    }
  }
}

Server Hook で指定したエンドポイントは、設定に基づいて自動実行できるほか、クライアント SDK から手動実行することもできます。

サーバートリガー起動

サーバートリガー起動用の Server Hook 定義方法を以下にまとめます。

{
  "<path>": [
    {
      "when": "<trigger>",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "<endpoint_name>"
    },
    /* more hooks */
  ],
  /* more paths with more hooks */
}

path で指定したエンティティに when で指定したトリガーが発生すると、endpoint で指定した Server Code 内の関数が実行されます。

ここで path は Bucket、User、Group、Thing、Installation のいずれかとなります。

  • Bucket:指定した Bucket で発生するトリガーをチェック。

    • path は以下のいずれかの形式で指定します。
      • kiicloud://buckets/<bucketID>:アプリケーションスコープの Bucket の場合。
      • kiicloud://groups/*/buckets/<bucketID>:グループスコープの Bucket の場合。
      • kiicloud://users/*/buckets/<bucketID>:ユーザースコープの Bucket の場合。
      • kiicloud://things/*/buckets/<bucketID>:Thing スコープの Bucket の場合。
    • 指定可能なトリガー(when)は以下のとおりです。
      • DATA_OBJECT_CREATED:指定した Bucket 内に新たな Object が作成された。
      • DATA_OBJECT_DELETED:指定した Bucket 内の Object が削除された。
      • DATA_OBJECT_UPDATED:指定した Bucket 内の Object が更新された。

    トリガーに関するパラメータは実行時パラメータとして Server Code に渡されます。詳細については こちら を参照してください。

  • User:任意のユーザーに発生するトリガーをチェック。

    • pathkiicloud://users と指定します。
    • 指定可能なトリガー(when)は以下のとおりです。
      • USER_CREATED:新たなユーザーが作成された。
      • USER_EMAIL_VERIFIED:ユーザーのメールアドレスが確認された。
      • USER_PHONE_VERIFIED:ユーザーの電話番号が確認された。
      • USER_PASSWORD_RESET_COMPLETED:ユーザーのパスワードがリセットされた。
      • USER_PASSWORD_CHANGED:ユーザーのパスワードが更新された。
      • USER_DELETED:ユーザーが削除された。
      • USER_UPDATED:ユーザーの属性が更新された。

    トリガーに関するパラメータは実行時パラメータとして Server Code に渡されます。詳細については こちら を参照してください。

    ユーザーの無効化 などのサポートされていないトリガーが必要な場合は、USER_UPDATED を設定し、無効化と同時にユーザーの属性を上書きするなどの方法を利用できます。

  • Group:任意のグループに発生するトリガーをチェック。

    • pathkiicloud://groups と指定します。
    • 指定可能なトリガー(when)は以下のとおりです。
      • GROUP_CREATED:新たなグループが作成された。
      • GROUP_DELETED:グループが削除された。
      • GROUP_MEMBERS_ADDED:新たなグループメンバーが追加された。
      • GROUP_MEMBERS_REMOVED:グループメンバーが削除された。

    トリガーに関するパラメータは実行時パラメータとして Server Code に渡されます。詳細については こちら を参照してください。

  • Thing:任意の Thing に発生するトリガーをチェック。

    • pathkiicloud://things と指定します。
    • 指定可能なトリガー(when)は以下のとおりです。
      • THING_CREATED:Thing が登録された。
      • THING_ENABLED:Thing が有効化された。
      • THING_DISABLED:Thing が無効化された。
      • THING_USER_OWNER_ADDED:ユーザーが Thing オーナーとして追加された。
      • THING_GROUP_OWNER_ADDED:グループが Thing オーナーとして追加された。
      • THING_USER_OWNER_REMOVED:ユーザーが Thing オーナーから削除された。
      • THING_GROUP_OWNER_REMOVED:グループが Thing オーナーから削除された。
      • THING_FIELDS_UPDATED:Thing 情報が更新された。
      • THING_DELETED:Thing が登録解除された。
      • THING_CONNECTED:Thing がオンラインになった(MQTT コネクションが確立された)。
      • THING_DISCONNECTED:Thing がオフラインになった(MQTT コネクションが切断された)。

    トリガーに関するパラメータは実行時パラメータとして Server Code に渡されます。詳細については こちら を参照してください。

  • Installation:プッシュ通知受け取り用にデバイスがインストールされたトリガーをチェック。

    • pathkiicloud://installations と指定します。
    • 指定可能なトリガー(when)は以下のとおりです。
      • INSTALLATION_CREATED:ユーザーがプッシュ通知受け取り用デバイスをインストールした。
      • INSTALLATION_DELETED:ユーザーがプッシュ通知受け取り用デバイスのインストールを解除した。

    トリガーに関するパラメータは実行時パラメータとして Server Code に渡されます。詳細については こちら を参照してください。

以下にサーバートリガー起動用の Server Hook の例を挙げます。

{
  "kiicloud://users": [
    {
      "when": "USER_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "main"
    }
  ]
}

この例では、新規ユーザーの作成を契機にエンドポイント main を実行するように定義をしています。たとえば こちらのサンプル Server Code と一緒にこの Server Hook を設置すると、新規ユーザーが作成されたタイミングで自動的にアイテム追加処理が実行されます。

同一のパスに対するトリガー

同一のパスに複数種類のトリガーを設定する場合、以下のように JSON 配列としてトリガーを定義します。同じパスを複数回記述すると、最後に記述したパスに対するトリガーだけが有効になるためご注意ください。

{
  "kiicloud://buckets/myBucket": [
    {
      "when": "DATA_OBJECT_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "func1"
    },
    {
      "when": "DATA_OBJECT_DELETED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "func2"
    }
  ]
}

なお、同一のトリガーに対して複数の "endpoint" は設定できません。たとえば、ユーザー作成のトリガーに対して func1func2 を呼び出すような設定を行うと、登録時にエラーメッセージが表示されます。このような設定が必要な場合は、Server Code の関数内で分岐するように実装してください。

スケジュール起動

スケジュール起動用の Server Hook 定義方法を以下にまとめます。

{
  "kiicloud://scheduler": {
    "<job_name>": {
      "cron": "<cron_expression>",
      "endpoint": "<endpoint_name>",
      "parameters": {
        "arg1": "xxxx"
      },
      "what": "EXECUTE_SERVER_CODE"
    }
    /* more hooks */
  }
  /* more paths with more hooks */
}

cron_expression で指定した時間が来ると、endpoint で指定した Server Code 内の関数が実行されます。各 Hook 定義には、後ほど実行結果履歴を参照する際に利用する job_name を付けます。また必要に応じて、Server Code に渡すパラメータを parameters プロパティに指定できます。

"kiicloud://scheduler" 以下には複数のスケジュールを定義できます。job_name に対する設定は JSON の name / value ペア(Map)として記述するため、設定ごとに必ず別の job_name を指定するようにします(重複していても、Kii Cloud への登録時、エラーにならないためご注意ください)。異なる名前で同一のスケジュールを定義した場合、設定されている数だけ Server Code 内の関数が実行されます。

cron_expression は次のように表記します。

時間は UTC(協定世界時)で指定してください。

また以下の特殊文字が利用できます。

  • アスタリスク(*):フィールドの任意の値にマッチします。
  • ハイフン(-):範囲指定に使います。
  • スラッシュ(/):間隔値指定に使います。たとえば第 1 フィールド(分)に "0/10" を指定すると「10 分間隔」という意味になります。
  • カンマ(,):複数値(値のリスト)の指定に使います。たとえば第 5 フィールド(曜日)に "MON,WED,FRI" を指定すると「月曜、水曜、金曜」という意味になります。

以下にいくつかの例を挙げます。

#毎時実行
0 * * * *

#毎日 00:01 に実行
1 0 * * *

#平日(月~金)の 05:00 に実行
0 5 * * MON-FRI

#毎日 2 時間おき(0 時、2 時、4 時、6 時…)に実行
0 0/2 * * *

#14:00 から 14:55 までの間、5 分おきに毎日実行
0/5 14 * * *

#週末(土~日)の 11:00 と 16:00 に実行
00 11,16 * * SUN,SAT

なお、cron_expression には以下の制限があります。

  • "*" と "/" は同時に使えません。

    • OK:0/5 14 * * *
    • NG:*/5 14 * * *
  • 1 つの cron 表記アイテム(分、時間、…)で使えるのは、範囲(例:4-7)、間隔値(例:2/5)、リスト(例:0,5,10,15)のいずれか 1 つのみです。複数の指定方法の併用はできません。

    • OK:0,5,10 21-23 * * MON-FRI
    • NG:5-8/2 * * * *
  • 月と曜日は同時に指定できません。

    • NG:0 0 1 1 SUN

以下にスケジュール起動用の Server Hook の例を挙げます。

{
  "DailyMessage_5am": {
    "cron": "0 5 * * *",
    "endpoint": "sendDailyMessage",
    "parameters": {
      "time": "5am"
    },
    "what": "EXECUTE_SERVER_CODE"
  },
  "DailyMessage_10pm": {
    "cron": "0 22 * * *",
    "endpoint": "sendDailyMessage",
    "parameters": {
      "time": "10pm"
    },
    "what": "EXECUTE_SERVER_CODE"
  }
}

この例は、毎日 5:00 と 22:00(UTC:協定世界時)にエンドポイント sendDailyMessage を実行します。またそれぞれの実行時に、異なったパラメータを Server Code に渡しています(この Server Hook と連動する Server Code の例は こちら を参照してください)。