Server Code の手動実行

Server Code はクライアントよりいつでも手動で実行できます。実行の際には、クライアント側より Server Code に実行時パラメータを渡すことができます。

Server Code を実行する方法を見ていきましょう。以下の Server Code が Kii Cloud に設置されていると仮定します。

function main(params, context, done) {
  var user = KiiUser.userWithUsername(params.username,
                                      params.password);
  user.register({
    success: function(user) {
      done(user.getUsername());
    },
    failure: function(user, errorString) {
      done(errorString);
    }
  });
}

このサンプルコードは こちらで例示したもの と同じものです。クライアントより実行時パラメータとして渡されたユーザーネームとパスワードを用いてユーザー登録処理を行います(友人の代わりに新規アカウント作成を代行するケースなどを想定したサンプル)。

なお、Server Code 内の success と failure は、クライアントでの成功と失敗に対応しない点にご注意ください。このサンプルコードの場合、Server Code 内の処理が failure で失敗しても、クライアントではエラー文字列を正常に受け取れるため、呼び出しは成功となります。クライアントのエラーは、Server Code の呼び出しそのものができなかった場合です。Server Code 内のエラーを返したい場合は、戻り値に成功/失敗のステータスを含めるように実装します。

REST API で Server Code を実行する

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
< 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" ヘッダの値として返されます。

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

同期的に書かれた Server Code における実行結果 非同期的に書かれた Server Code における実行結果 クライアントへの応答内容
return 1; done(1); {"returnedValue":1}
return "resp"; done("resp"); {"returnedValue":"resp"}
return true; done(true); {"returnedValue":true}
return {name:"Kii", zip:"123456"}; done({name:"Kii", zip:"123456"}); {"returnedValue":{name:"Kii", zip:"123456"}}
return ["one", "two"]; done(["one", "two"]); {"returnedValue":["one", "two"]}

タイムアウト

制限事項 に記載されているように、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"
    }
  }
}

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

Android SDK より Server Code を実行する

Android SDK より Server Code を実行する例を以下に挙げます。

  • // Instantiate with the endpoint.
    KiiServerCodeEntry entry = Kii.serverCodeEntry("main");
    
    try {
      JSONObject rawArg = new JSONObject();
    
      // Set the custom parameters.
      rawArg.put("username", "name_of_my_friend");
      rawArg.put("password", "password_for_my_friend");
      KiiServerCodeEntryArgument arg = KiiServerCodeEntryArgument
          .newArgument(rawArg);
    
      // Execute the Server Code
      KiiServerCodeExecResult res = entry.execute(arg);
    
      // Parse the result.
      JSONObject returned = res.getReturnedValue();
      String newUser = returned.getString("returnedValue");
    
      // Get the number of the executed steps.
      int steps = res.getExecutedSteps();
    
    } catch (AppException e) {
      // Handle the error.
    } catch (IOException e) {
      // Handle the error.
    } catch (JSONException e) {
      // Handle the error.
    }
  • // Instantiate with the endpoint.
    KiiServerCodeEntry entry = Kii.serverCodeEntry("main");
    
    JSONObject rawArg = new JSONObject();
    try {
      // Set the custom parameters.
      rawArg.put("username", "name_of_my_friend2");
      rawArg.put("password", "password_for_my_friend");
    } catch (JSONException e) {
      // Handle the error.
    }
    KiiServerCodeEntryArgument arg = KiiServerCodeEntryArgument
        .newArgument(rawArg);
    
    // Execute the Server Code
    entry.execute(arg, new KiiServerCodeEntryCallback() {
      public void onExceuted(KiiServerCodeEntry entry, KiiServerCodeEntryArgument argument,
                             KiiServerCodeExecResult res, Exception exception) {
        if (exception != null) {
          // Handle the error.
          return;
        }
        // Parse the result.
        try {
          JSONObject returned = res.getReturnedValue();
          String newUser = returned.getString("returnedValue");
    
          // Get the number of the executed steps.
          int steps = res.getExecutedSteps();
        } catch (JSONException e) {
          // Handle the error.
        }
      }
    });

ここでは以下の処理が行われています。

  • 実行対象エンドポイント名(関数名)を指定して serverCodeEntry メソッドを実行し、KiiServerCodeEntry インスタンスを作成。
  • 実行時パラメータ(今回の例ではユーザー名とパスワード)を JSON オブジェクトに格納し、これを指定して newArgument メソッドを実行し、KiiServerCodeEntryArgument インスタンスを作成。この際、実行時パラメータのキーを Server Code 内のキーと一致させてください(今回の例では "username" と "password")。
  • 実行時パラメータを指定して execute メソッドを実行し、Server Code を実行。
    • ユーザーがログインしている場合、Kii Cloud はこのユーザーにより Server Code が実行されたものと見なします。
    • ユーザーがログインしていない場合、Kii Cloud は匿名ユーザーにより Server Code が実行されたものと見なします。
  • getReturnedValue メソッドを実行して、実行結果を取得。
  • (必要に応じて)getExecutedSteps メソッドを実行して、実行ステップ数を取得。

getReturnedValue メソッドは、こちら で例示したような、Server Code を実行した結果が "returnedValue" フィールドに格納された JSON オブジェクトを返します。実際の結果を抽出するには、適切なメソッドを実行してください。今回の例の場合は getString メソッドを使い、新規に作成されたユーザー名の取得を行っています。

タイムアウト時に返却する値を設定した場合、同様に getReturnedValue メソッドを使って値を取得します。メソッドで取得可能な JSON オブジェクトは こちら をご参照ください。

iOS SDK より Server Code を実行する

iOS SDK より Server Code を実行する例を以下に挙げます。

Objective-C:

  • // Instantiate with the endpoint.
    KiiServerCodeEntry* entry =[Kii serverCodeEntry:@"main"];
    
    // Set the custom parameters.
    NSDictionary* argDict= [NSDictionary dictionaryWithObjectsAndKeys:
                             @"name_of_my_friend", @"username",
                             @"password_for_my_friend", @"password", nil];
    KiiServerCodeEntryArgument* argument= [KiiServerCodeEntryArgument argumentWithDictionary:argDict];
    
    // Execute the Server Code.
    NSError* error = nil;
    KiiServerCodeExecResult* result = [entry executeSynchronous:argument
                                                      withError:&error];
    if (error != nil) {
      // Handle the error.
      return;
    }
    
    // Parse the result.
    NSDictionary *returnedDict = [result returnedValue];
    NSString *newUser = [returnedDict objectForKey:@"returnedValue"];
    
    // Get the number of the exectued steps.
    int execSteps = (int)[result executedSteps];
  • // Instantiate with the endpoint.
    KiiServerCodeEntry* entry =[Kii serverCodeEntry:@"main"];
    
    // Set the custom parameters.
    NSDictionary* argDict= [NSDictionary dictionaryWithObjectsAndKeys:
                             @"name_of_my_friend", @"username",
                             @"password_for_my_friend", @"password", nil];
    KiiServerCodeEntryArgument* argument= [KiiServerCodeEntryArgument argumentWithDictionary:argDict];
    
    // Execute the Server Code.
    NSError* error = nil;
    [entry execute:argument
         withBlock:^(KiiServerCodeEntry *entry, KiiServerCodeEntryArgument *argument, KiiServerCodeExecResult *result, NSError *error) {
      if (error != nil) {
        // Handle the error.
        return;
      }
      // Parse the result.
      NSDictionary *returnedDict = [result returnedValue];
      NSString *newUser = [returnedDict objectForKey:@"returnedValue"];
    
      // Get the number of the exectued steps.
      int execSteps = (int)[result executedSteps];
    }];

Swift 2.3:

  • let entry = Kii.serverCodeEntry("main")
    let argDict = ["username":"name_of_my_friend","password":"password_for_my_friend"]
    let argument = KiiServerCodeEntryArgument(dictionary:argDict)
    
    let result : KiiServerCodeExecResult
    do{
      result = try entry.executeSynchronous(argument)
    }catch(let error as NSError){
      // Handle the error.
      return
    }
    // Parse the result.
    let returnedDict = result.returnedValue()
    let newUser = returnedDict?["returnedValue"];
    
    // Get the number of the exectued steps.
    let execSteps : Int = result.executedSteps()
  • let entry = Kii.serverCodeEntry("main")
    let argDict = ["username":"name_of_my_friend","password":"password_for_my_friend"]
    let argument = KiiServerCodeEntryArgument(dictionary:argDict)
    entry.execute(argument) { (retEntry : KiiServerCodeEntry, retArg : KiiServerCodeEntryArgument?, result : KiiServerCodeExecResult?, error : NSError?) in
      if error != nil {
        // Handle the error.
        return
      }
      // Parse the result.
      let returnedDict = result?.returnedValue()
      let newUser = returnedDict?["returnedValue"];
    
      // Get the number of the exectued steps.
      let execSteps : Int = result!.executedSteps()
    }

Swift 3:

  • let entry = Kii.serverCodeEntry("main")
    let argDict = ["username":"name_of_my_friend","password":"password_for_my_friend"]
    let argument = KiiServerCodeEntryArgument(dictionary:argDict)
    
    let result : KiiServerCodeExecResult
    do{
      result = try entry.executeSynchronous(argument)
    }catch(let error as NSError){
      // Handle the error.
      return
    }
    // Parse the result.
    let returnedDict = result.returnedValue()
    let newUser = returnedDict?["returnedValue"];
    
    // Get the number of the exectued steps.
    let execSteps : Int = result.executedSteps()
  • let entry = Kii.serverCodeEntry("main")
    let argDict = ["username":"name_of_my_friend","password":"password_for_my_friend"]
    let argument = KiiServerCodeEntryArgument(dictionary:argDict)
    entry.execute(argument) { (retEntry : KiiServerCodeEntry, retArg : KiiServerCodeEntryArgument?, result : KiiServerCodeExecResult?, error : Error?) in
      if error != nil {
        // Handle the error.
        return
      }
      // Parse the result.
      let returnedDict = result?.returnedValue()
      let newUser = returnedDict?["returnedValue"];
    
      // Get the number of the exectued steps.
      let execSteps : Int = result!.executedSteps()
    }

ここでは以下の処理が行われています。

  • 実行対象エンドポイント名(関数名)を指定して serverCodeEntry メソッドを実行し、KiiServerCodeEntry インスタンスを作成。
  • 実行時パラメータ(今回の例ではユーザー名とパスワード)を NSDictionary に格納し、これを指定して argumentWithDictionary メソッドを実行し、KiiServerCodeEntryArgument インスタンスを作成。この際、実行時パラメータのキーを Server Code 内のキーと一致させてください(今回の例では "username" と "password")。
  • 実行時パラメータを指定して executeSynchronous メソッドを実行し、Server Code を実行。
    • ユーザーがログインしている場合、Kii Cloud はこのユーザーにより Server Code が実行されたものと見なします。
    • ユーザーがログインしていない場合、Kii Cloud は匿名ユーザーにより Server Code が実行されたものと見なします。
  • returnedValue メソッドを実行して、実行結果を取得。
  • (必要に応じて)executedSteps メソッドを実行して、実行ステップ数を取得。

returnedValue メソッドは、こちら で例示したような、Server Code を実行した結果が "returnedValue" フィールドに格納された NSDictionary を返します。実際の結果を抽出するには、適切なメソッドを実行してください。

タイムアウト時に返却する値を設定した場合、同様に returnedValue メソッドを使って値を取得します。メソッドで取得可能な NSDictionary は こちら をご参照ください。

Unity SDK より Server Code を実行する

Unity SDK より Server Code を実行する例を以下に挙げます。

// Instantiate with the endpoint.
KiiServerCodeEntry entry = Kii.ServerCodeEntry("main");

JsonObject rawArg = new JsonObject();

// Set the custom parameters.
rawArg.Put("username", "name_of_my_friend");
rawArg.Put("password", "password_for_my_friend");
KiiServerCodeEntryArgument arg = KiiServerCodeEntryArgument
    .NewArgument(rawArg);

// Execute the Server Code
entry.Execute(arg, (KiiServerCodeEntry retEntry, KiiServerCodeEntryArgument args,
                    KiiServerCodeExecResult result, Exception e) => {
  if (e != null)
  {
    // Handle the error.
    return;
  }
  // Parse the result.
  JsonObject returned = result.ReturnedValue;
  string newUser = returned.GetString("returnedValue");

  // Get the number of the executed steps.
  int steps = result.ExecutedSteps;
});

ここでは以下の処理が行われています。

  • 実行対象エンドポイント名(関数名)を指定して ServerCodeEntry メソッドを実行し、KiiServerCodeEntry インスタンスを作成。
  • 実行時パラメータ(今回の例ではユーザー名とパスワード)を JSON オブジェクトに格納し、これを指定して NewArgument メソッドを実行し、KiiServerCodeEntryArgument インスタンスを作成。この際、実行時パラメータのキーを Server Code 内のキーと一致させてください(今回の例では "username" と "password")。
  • 実行時パラメータを指定して Execute メソッドを実行し、Server Code を実行。
    • ユーザーがログインしている場合、Kii Cloud はこのユーザーにより Server Code が実行されたものと見なします。
    • ユーザーがログインしていない場合、Kii Cloud は匿名ユーザーにより Server Code が実行されたものと見なします。
  • ReturnedValue プロパティで、実行結果を取得。
  • (必要に応じて)ExecutedSteps プロパティで、実行ステップ数を取得。

ReturnedValue プロパティは、こちら で例示したような、Server Code を実行した結果が "returnedValue" フィールドに格納された JSON オブジェクトです。実際の結果を抽出するには、適切なメソッドを実行してください。今回の例の場合は GetString メソッドを使い、新規に作成されたユーザー名の取得を行っています。

タイムアウト時に返却する値を設定した場合、同様に ReturnedValue プロパティより値を取得します。プロパティより取得可能な JSON オブジェクトは こちら をご参照ください。

JavaScript SDK より Server Code を実行する

JavaScript SDK より Server Code を実行する例を以下に挙げます。

// Instantiate with the endpoint.
var entry = Kii.serverCodeEntry("main");

// Set the custom parameters.
var arg = {"username":"name_of_my_friend", "password":"password_for_my_friend"};

// Execute the Server Code
entry.execute(arg,{

    success: function(entry, argument, execResult) {
      // do something now that the user is logged in

      // Parse the result.
      var returned = execResult.getReturnedValue();
      var newUser = returned["returnedValue"];

      // Get the number of the executed steps.
      var steps = execResult.getExecutedSteps();
    },

    failure: function(entry, argument,execResult, anErrorString) {
      // do something with the error response
    }
  }
);

ここでは以下の処理が行われています。

  • 実行対象エンドポイント名(関数名)を指定して serverCodeEntry メソッドを実行し、KiiServerCodeEntry インスタンスを作成。
  • 実行時パラメータ(今回の例ではユーザー名とパスワード)を JSON オブジェクトに格納し、これを指定して newArgument メソッドを実行し、KiiServerCodeEntryArgument インスタンスを作成。この際、実行時パラメータのキーを Server Code 内のキーと一致させてください(今回の例では "username" と "password")。

  • 実行時パラメータを指定して execute メソッドを実行し、Server Code を実行。

    • ユーザーがログインしている場合、Kii Cloud はこのユーザーにより Server Code が実行されたものと見なします。
    • ユーザーがログインしていない場合、Kii Cloud は匿名ユーザーにより Server Code が実行されたものと見なします。
  • getReturnedValue メソッドを実行して、実行結果を取得。

  • (必要に応じて)getExecutedSteps メソッドを実行して、実行ステップ数を取得。

getReturnedValue メソッドは、こちら で例示したような、Server Code を実行した結果が "returnedValue" フィールドに格納された JSON オブジェクトを返します。実際の結果を抽出するには、適切なメソッドを実行してください。

タイムアウト時に返却する値を設定した場合、同様に getReturnedValue メソッドを使って値を取得します。メソッドで取得可能な JSON オブジェクトは こちら をご参照ください。

Thing SDK Embedded より Server Code を実行する

Thing SDK Embedded を使うと、Thing から Server Code を実行できます。実行方法は Server Code の実行 をご覧ください。