キーと値のペアの設定

KiiObject にキーと値のペアを設定するには、KiiObject クラスの set() メソッドを呼び出します。set() メソッドの引数には任意の型を指定できます。

set() メソッドの引数には、キー名と値を設定します。指定したキーと値のペアは JSON ドキュメントの第 1 階層として保存されます。

以下に値を設定するためのサンプルコードを示します。KiiObject の保存処理まで含む完全なコードは、KiiObject の作成、または、下記の 基本データ型の設定 を参照してください。また、KiiObject の更新 でも値の設定を行います。

var object = bucket.createObject();
obj.set("score", 987);
obj.set("mode", "easy");
obj.set("premiumUser", false);

このコードを実行後、KiiObject を保存すると、JSON 形式のデータが作成されます(管理用フィールドは省略しています)。

{
  "score": 987,
  "premiumUser": false,
  "mode": "easy"
}

第 2 階層より深い位置に値を書き込みたい場合は、目的の階層に値をセットした JSONObject を第 1 階層に書き込んでください。

1 つの KiiObject に格納できるデータの最大サイズは、キーと値のペアを JSON 形式で表現した状態で 65534 文字までです(サイズには Kii Cloud が内部で使用するフィールドも含まれます)。

サポートするデータ型

set() メソッドの値部分は、以下の表に示す型を指定できます。

Kii Cloud に格納できる数値の範囲には制限がないため、各型で表現可能な最大値を格納することができます。

表の「JSON での値の格納結果」は、開発者ポータルのデータブラウザーで確認したり、他のプラットフォームで参照したりする際の参考として利用できます。格納と参照を同じ型で行う場合、JSON での格納結果を意識する必要は特にありません。

値の型 呼び出し例 JSON での値の格納結果 備考
string set("data", "123"); "data":"123"
number set("data", 123); "data":123
boolean set("data", true); "data":true
KiiGeoPoint set("data", geoPoint); "data":{
"_type": "point",
"lat": 35.658603,
"lon": 139.745433
}
geoPoint が (35.658603, 139.745433) の場合
配列 set("data", array); "data":[1,2,3] array が [1,2,3] の場合
object set("data", json); "data":{"a":"b"} json が {"a":"b"} の場合
  • 値として null を設定する方法はありません。設定すると無視またはエラーとなります。
  • 日付型(Date)を設定したい場合、valueOf() メソッドにより、1970 年 1 月 1 日 00:00:00 UTC からのミリ秒数を number 型のデータとして格納すれば扱いが簡単になります。
  • JavaScript では Android にある、バイト配列を BASE64 にして出力する機能はサポートしていません。

基本データ型の設定

KiiObject の新規作成時に、string、number、boolean の各データ型を格納する例を以下に示します。

なお、以下のサンプルコードは、KiiObject の作成 のサンプルコードより、値の格納部分を変更したものです。

  • // Create a KiiObject.
    var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();
    
    // Set key-value pairs.
    obj.set("stringValue", "my value");
    obj.set("intValue", 123);
    obj.set("longValue", new Date().valueOf());
    obj.set("doubleValue", 987.654);
    obj.set("booleanValue", true);
    
    // Save the KiiObject.
    obj.save({
      success: function(theObject) {
        // Do something.
      },
      failure: function(theObject, errorString) {
        // Handle the error.
      }
    });
  • // Create a KiiObject.
    var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();
    
    // Set key-value pairs.
    obj.set("stringValue", "my value");
    obj.set("intValue", 123);
    obj.set("longValue", new Date().valueOf());
    obj.set("doubleValue", 987.654);
    obj.set("booleanValue", true);
    
    // Save the KiiObject.
    obj.save().then(
      function(theObject) {
        // Do something.
      }
    ).catch(
      function(error) {
        var theObject = error.target;
        var errorString = error.message;
        // Handle the error.
      }
    );

このコードを実行すると、KiiObject には以下のような JSON 形式のデータが作成されます(管理用フィールドは省略しています)。

{
  "stringValue": "my value",
  "booleanValue": true,
  "longValue": 1495677489018,
  "doubleValue": 987.654,
  "intValue": 123
}

位置情報(GeoPoint)の設定

次に、KiiObject に位置情報(GeoPoint)をセットする方法を説明します。

位置情報を格納するには、まず緯度と経度を指定して KiiGeoPoint オブジェクトを作成します。この後、作成した KiiGeoPoint を値として持つキーと値のペアを setGeoPoint() メソッドを用いて KiiObject にセットします。

例として、現在ログイン中のユーザーのユーザースコープに存在する "MyBucket" という Bucket 内に KiiObject を作成し、これに位置情報を 2 つセットするサンプルコードを以下に挙げます。

  • // Create a KiiObject.
    var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();
    
    // Create GeoPoint objects.
    var point1 = KiiGeoPoint.geoPoint(35.658603, 139.745433);
    var point2 = KiiGeoPoint.geoPoint(35.658625, 139.745415);
    
    // Set the GeoPoints to the KiiObject.
    obj.setGeoPoint("location1",point1);
    obj.setGeoPoint("location2",point2);
    
    // Save the KiiObject.
    obj.save({
      success: function(theObject) {
        // Do something.
      },
      failure: function(theObject, errorString) {
        // Handle the error.
      }
    });
  • // Create a KiiObject.
    var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();
    
    // Create GeoPoint objects.
    var point1 = KiiGeoPoint.geoPoint(35.658603, 139.745433);
    var point2 = KiiGeoPoint.geoPoint(35.658625, 139.745415);
    
    // Set the GeoPoints to the KiiObject.
    obj.setGeoPoint("location1",point1);
    obj.setGeoPoint("location2",point2);
    
    // Save the KiiObject.
    obj.save().then(
      function(theObject) {
        // Do something.
      }
    ).catch(
      function(error) {
        var theObject = error.target;
        var errorString = error.message;
        // Handle the error.
      }
    );

save() メソッドの実行を忘れないでください。save() メソッドを実行するまで、KiiObject にセットしたキーと値のペアは Kii Cloud に反映されません。

複雑なデータ型の設定

単純なデータ型以外にも、JSON オブジェクト、JSON オブジェクトの配列などのデータ型をサポートしています。

以下にこれらのデータ型の値を格納する例を挙げます。

  • // Create a KiiObject.
    var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();
    
    // Set a value of a JSON object.
    obj.set("myObject", {"score": 987, "mode": "easy"});
    
    // Set a value of a JSON array.
    obj.set("myArray", [{"Name": "Alice", "age": 30},
                        {"Name": "Bob", "age": 28}]);
    
    // Save the KiiObject.
    obj.save({
      success: function(theObject) {
        // Do something.
      },
      failure: function(error) {
        var theObject = error.target;
        var errorString = error.message;
        // Handle the error.
      }
    });
  • // Create a KiiObject.
    var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();
    
    // Set a value of a JSON object.
    obj.set("myObject", {"score": 987, "mode": "easy"});
    
    // Set a value of a JSON array.
    obj.set("myArray", [{"Name": "Alice", "age": 30},
                        {"Name": "Bob", "age": 28}]);
    
    // Save the KiiObject.
    obj.save().then(
      function(theObject) {
        // Do something.
      }
    ).catch(
      function(error) {
        var theObject = error.target;
        var errorString = error.message;
        // Handle the error.
      }
    );

save() メソッドの実行を忘れないでください。save() メソッドを実行するまで、KiiObject にセットしたキーと値のペアは Kii Cloud に反映されません。

このコードを実行すると、KiiObject には以下のような JSON 形式のデータが作成されます(管理用フィールドは省略しています)。

{
  "myArray": [
    {
      "Name": "Alice",
      "age": 30
    },
    {
      "Name": "Bob",
      "age": 28
    }
  ],
  "myObject": {
    "score": 987,
    "mode": "easy"
  }
}