Server Code の機能

Kii Cloud では、Server Code の実行形態として、このページに示す 4 通りの方法をサポートしており、実現したい機能に応じてこれらを使い分けることができます。

いずれの場合も、Server Code 内に定義されたエンドポイントから実行が開始されます。エンドポイントとは、サーバー機能拡張によって定められた型を持つ JavaScript の関数です。

たとえば、以下は "Hello!" という文字列を返すように実装されたエンドポイント funcName です（記述方法の詳細は Server Code の書式をご覧ください）。

function funcName(params, context) {
  // Your code comes here...
  return "Hello!";
}

実際のコードでは、Kii Cloud SDK や外部のサーバーの呼び出しなど、サービスに必要な任意の処理を記述できます。エンドポイントの関数名 funcName は、呼び出し時の API や設定ファイルから指定します。

なお、1 つのエンドポイントを複数の方法で実行することもできます。たとえば、普段はスケジュール実行されているエンドポイントを、必要時にのみ手動実行するような使い方もできます。

手動実行

手動実行は、Kii Cloud に登録された Server Code を Kii Cloud SDK や REST API から呼び出して、サーバー上で実行する機能です。呼び出し元は、実行結果だけをレスポンスとして受け取ります。

以下に手動実行のイメージを示します（正確な書式については Server Code の書式および Server Code の手動実行をご覧ください）。

ここでは、Server Code 内にあるエンドポイント add、sub のうち、クライアントから add を指定して呼び出しています。Server Code は Kii Cloud 内で動作し、クライアントへは実行結果だけが返ります。

Server Code の永久ループを防止するため、Server Code から Kii Cloud SDK や REST API を使って、さらに Server Code を起動すると、エラーを返します。

Server Hook（サーバートリガー起動）

Kii Cloud 内のデータが更新されたタイミングをきっかけとして、Server Code を Kii Cloud 上で自動的に実行する機能です。自動実行の契機となるイベントをトリガーと呼びます。トリガーと実行したいエンドポイントは、Server Hook 設定ファイルによって関連付けます。

この機能を使うと、たとえば、ユーザーが作成されたときに初期データを自動的に書き込む処理や、Bucket 内の Object が更新されたときにデータを自動的に集計する処理などを実現できます。この機能を応用すれば、新規ゲームユーザーによるアカウント作成を契機に、Server Code を実行して初回プレゼントアイテムを配布するような用途に使えます。

下記にトリガー起動のイメージを示します（正確な書式については Server Code の書式および Server Hook 設定ファイルをご覧ください）。実際の Server Hook 設定ファイルは JSON 形式のファイルとして記述します。

利用できるトリガーには以下のようなものがあります（完全な一覧はサーバートリガー起動をご覧ください）。Server Hook 設定ファイルには、これらのトリガーの 1 つと、Server Code 上のエンドポイント 1 つのセットを、複数件設定できます。

対象	トリガー
Bucket	指定された Bucket に対する Object の作成、削除、更新
User	ユーザーの作成/削除、メールアドレス/電話番号の認証、パスワードのリセット/更新、ユーザー属性の更新
Group	グループの作成、削除、メンバーの追加/削除
Thing	Thing の登録/登録解除、有効化/無効化、オーナー追加/削除、Thing 情報の更新
Installation	プッシュ通知受け取り用のデバイスの登録と解除

いずれの場合も、トリガーによって Server Code が起動すると、変化したデータの詳細を関数の引数値として取得できます。たとえば、作成されたユーザーの ID や URL、更新された Bucket と Object の ID や URL などが取得できます。

Server Code の永久ループを防止するため、トリガーで起動された Server Code から、さらに別のトリガーを起動するようなデータが更新された場合、サーバートリガー起動は行いません。ただし、手動実行された Server Code でデータが更新された場合はサーバートリガー起動の対象となります。

Server Hook（スケジュール起動）

スケジュール起動は、指定した日時が来るごとに Server Code をサーバー上で自動的に実行する機能です。登録時に、Server Code のエンドポイントと、それが実行される日時を Server Hook 設定ファイルによって設定します。

スケジュール起動を使用すると、定期的な繰り返し処理が実現できるため、データの定期的なクリーンアップ処理や集計処理などを容易に実現できます。

下記にスケジュール起動のイメージを示します（正確な書式については Server Code の書式および Server Hook 設定ファイルをご覧ください）。実際の Server Hook 設定ファイルは JSON 形式のファイルとして記述します。

図の例では、指定された日時である毎日 3:00（UTC：協定世界時）になると、エンドポイント cleanup が引数値 time = 3am とともに呼び出されます。

サーバートリガー起動と同様に、Server Hook 設定ファイルにスケジュール起動のタイミングとエンドポイント名を記述すると、設定した時刻に Server Code が自動的に実行されます。Server Hook 設定ファイル上に複数の時刻とエンドポイントを記述することで、異なる間隔で自動実行することもできます。

時刻は、月、日、時、分、曜日の組み合わせと、その繰り返しや値の一覧として設定できます。たとえば、毎時 0 分のような単純なもののほか、週末（土～日）の 11:00 と 16:00 に実行などの柔軟な設定もできます。

Server Code の永久ループを防止するため、スケジュールで起動された Server Code から、さらに別のトリガーを起動するようなデータが更新された場合、サーバートリガー起動は行いません。

Thing-IF のトリガー

Thing-IF SDK を使って IoT ソリューションを構築する際、Server Code の自動実行を行うトリガーを登録できます。

Thing-IF SDK では Thing から登録されたステートが条件を満たしたとき、トリガーに設定された処理を自動実行することができます。トリガーに特定の Server Code のエンドポイントやパラメータを設定しておくことで、Server Code を指定された条件で自動実行できます。

Thing-IF のトリガーの詳細はトリガーによる自動実行をご覧ください。

Thing-IF のトリガーによって Server Code を実行する際、Server Code の実装方法は、手動実行の場合と同じです。Server Code の実行結果の取得方法など、Thing-IF に固有の機能は Thing-IF SDK の説明をご覧ください。