REST API からの実行

REST API で Server Code を実行する例を以下に挙げます。

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/server-code/versions/current/main" \
  -d '{"username": "name_of_my_friend", "password": "password_for_my_friend"}'

• 実行時パラメータとして "username" と "password" の値をサーバーに渡しています。
• API をコールする際に、実行対象エンドポイント（関数）として "main" を指定しています。
• アクセストークンの指定は省略することもできます。省略した場合は匿名ユーザーが Server Code を実行したと見なされます。

この結果 Server Code の "main" という関数が実行されます。サンプルの Server Code では KiiUser.userWithUsername() メソッドにおいて実行時パラメータを使用しています。実行時パラメータのキー（"usename" と "password"）が、Server Code 内のものと一致していることがわかります。

実行の結果、以下の様な応答が返されます。

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Origin: *
< X-Step-count: 3
< X-Environment-version: 0
< Content-Type: application/json;charset=UTF-8
< Cache-Control: max-age=0
< Content-Length: 27
< Accept-Ranges: bytes
< Date: Tue, 23 Jul 2013 03:57:28 GMT
< X-Varnish: 1572330455
< Age: 0
< Via: 1.1 varnish
< Connection: keep-alive
<
* Connection #0 to host js-box-tmp.internal.kii.com left intact
{"returnedValue":"name_of_my_friend"}
* Closing connection #0

この応答例のように Server Code の実行結果は "returnedValue" フィールドに入ります。またステップ数が "X-Step-count" ヘッダの値、実行した Node.js のバージョンが "X-Environment-version" ヘッダの値として返されます。

Server Code を手動実行して別の Server Code を呼び出すことはできません。実行すると、HTTP ステータス 409 で "OPERATION_NOT_ALLOWED" エラーになります。

戻り値の型

Server Code は様々な型のデータを実行結果として返すことができます。Server Code の実行結果がどのように返されるかを以下の表にまとめます（ここでは、非同期的に書かれたコードにおける結果返却用コールバック関数の名前が "done" であると仮定しています）。

タイムアウト

制限事項 に記載されているように、Server Code の実行時間が 20000 msec を超えるとタイムアウトが発生します。

タイムアウトが発生した場合、通常は次のような 400 応答が返されます。

{
  "errorCode" : "ENDPOINT_INVOCATION_ERROR",
  "message" : "Error found while executing the developer-defined code",
  "details" : {
    "errorCode" : "EXECUTION_TIMEOUT",
    "message" : "execution timeout. limit=20000ms"
  }
}

Server Code の書式 で解説した方法でタイムアウト時に返却する値を設定した場合は、400 応答ではなく 200 応答が返されます。この際、次のように _timeoutResponse フィールドの値として Server Code 側で設定した値が返されます。

{
  "returnedValue":{
    "_timeoutResponse":{
      "customField": "my_custom_message"
    }
  }
}

設定した値は 通常の実行結果 と同様に取得可能です。

JavaScript エンジンの指定

Server Code を実行する際に使用する JavaScript エンジン のバージョンを指定できます。指定されたバージョンは、Server Code の登録時に設定されているバージョンより優先されます。

JavaScript エンジンの指定例を以下に示します。

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/server-code/versions/current/main?environment-version=6" \
  -d '{"username": "name_of_my_friend", "password": "password_for_my_friend"}'

JavaScript エンジンは、URL の environment-version パラメーターで指定します。指定できる値は、以下のとおりです。指定した JavaScript エンジンが利用できない場合はエラーを返します。

environment-version を省略した場合は、Server Code の実行対象のバージョンに設定されている JavaScript エンジン、または、デフォルトの JavaScript エンジンが使用されます。