Server Code の書式

Server Code を記述するときは、このページの書式に従って実装します。

Server Code は、通常の JavaScript コードと同様に書くことができます。さらに Kii Cloud SDK for JavaScript を利用することで、Kii Cloud が提供する様々な機能を利用できます（Kii Cloud SDK for JavaScript の詳細については JavaScript リファレンスガイドを参照してください）。

Kii Cloud SDK for JavaScript には v2 系と v3 系が存在します。Server Code では v2 系の機能が利用できます。
詳しくは Kii Cloud SDK for JavaScript v2 系と v3 系の違いをご覧ください。

同期的な Server Code と非同期的な Server Code

Server Code は同期的・非同期的のいずれの方法でも書くことが可能です。いずれも基本的な構文は同じですが、非同期的な実行では、第 3 引数にコールバック関数が渡される点が異なります。

同期的な Server Code

同期的な Server Code の書式は以下のとおりです。関数が呼び出されると、コードが順に実行され、関数が return した時点で Server Code の実行が完了します。
```
function funcName(params, context) {
  // Your code comes here...
  return "Hello!";
}
```
非同期的な Server Code

非同期的な Server Code の書式は以下のとおりです。関数が終了しても Server Code の終了とは見なされず、第 3 引数のコールバック done が呼び出された後、関数から制御が戻った時点で実行が完了します（非同期的な実行に示すように、done の呼び出し後に関数自身も終了する必要があります）。
```
function funcName(params, context, done) {
  // Your code comes here...
  done("Hello!");
}
```
ノンブロッキング API などの非同期的な呼び出しが前提の機能を使用する場合は、こちらの形式を使用する必要があります。

エンドポイントのパラメーター

エンドポイントのパラメーターは、Server Code の実行形態によって異なります。それぞれの実行形態でのパラメーターは以下に示すとおりです。

作成したエンドポイントを複数の機能から呼び出されるように設置した場合（たとえば、1 つの関数を手動実行とサーバートリガー起動の両方で共有するような場合）では、呼び出された状況に応じてパラメータの内容や API が返す値が変化します。

非同期的な実行

非同期的な実行では、第 3 引数のコールバック関数の実行、または、例外の throw によって Server Code の終了を識別します。特に結果を返す必要がない場合やエラー終了する場合においても、処理の完了時に必ずコールバック関数を実行してください（例外を throw した場合には呼び出しは不要です）。実行しなかった場合、タイムアウト例外が発生します。

特に、コールバック関数の failure を省略した場合や、Promise の利用時に catch ハンドラーを適切に記述しなかった場合、done() が呼び出されないパスが存在することになります。この場合、Server Code がタイムアウトするためご注意ください。

done コールバック関数を実行しても Server Code 自体は終了しないことに注意してください。たとえば以下の Server Code を実行した場合、done("ERROR!!") が実行された後でも続けて done("SUCCESS!!") が実行されます。

function asyncFunc(params, context, done) {
  if (!context.getAccessToken()) {
    done("ERROR!!");
    // You need a return statement here.
  }
  done("SUCCESS!!");
}

実際の処理では、必ずコールバックの後に return で関数を終了するなどして、コールバック関数を 1 回だけ呼び出すようなロジックにする必要があります。コールバック関数が 2 回以上呼び出された場合、初めの値が戻り値となりますが、2 回目以降の呼び出しは Warning として開発者ログに記録されます。

また、ノンブロッキング API を使用する場合、done の呼び出しを行った後でも、ノンブロッキング API へのコールバックは実行されます。たとえば、以下の Server Code では、ログイン終了のコールバック関数は実行されて、ログが出力されます。下記のコードの done は、実際に実行される処理の最後（ここではコールバックの内部）で呼び出すように修正する必要があります。

function asyncFunc(params, context, done) {
  KiiUser.authenticate("aaaa", "bbbb", {
    success: function(theUser) {
      console.log("User authenticated!");
      // Call the done() function here.
    },
    failure: function(theUser, errorString) {
      console.log("Error authenticating: " + errorString);
      // Call the done() function here.
    }
  });
  done("OK");  // You shouldn't call the done() function here.
}

非同期的な実行を行うと、ネストが深くなって可読性が低下します。JavaScript SDK がサポートしている Promise の利用をおすすめします。また、jQuery.Deferred() も利用できます。

タイムアウト

タイムアウトが発生した場合、通常は例外がスローされます。

タイムアウト発生時にクライアントに特定の値を返すことも可能です。この場合は、以下の例のように context オブジェクトに返したい値を設定します。

function main(params, context, done) {
    context._timeoutReponse = {customField: "my_custom_message"};
}

上記の指定を行った場合、タイムアウト時に例外はスローされず正常終了として処理されます。クライアント側では、指定した値を通常の実行結果と同様に取得できます。詳しくはこちらをご参照ください。

Server Code の書式

同期的な Server Code と 非同期的な Server Code

エンドポイントのパラメーター

非同期的な実行

タイムアウト

同期的な Server Code と非同期的な Server Code