キーと値のペアの設定

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().then(
  function(theObject) {
    // Do something.
  }
).catch(
  function(error) {
    var theObject = error.target;
    var errorString = error.message;
    // 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({
  success: function(theObject) {
    // Do something.
  },
  failure: function(theObject, errorString) {
    // 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().then(
  function(theObject) {
    // Do something.
  }
).catch(
  function(error) {
    var theObject = error.target;
    var errorString = error.message;
    // 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({
  success: function(theObject) {
    // Do something.
  },
  failure: function(theObject, errorString) {
    // 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().then(
  function(theObject) {
    // Do something.
  }
).catch(
  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({
  success: function(theObject) {
    // Do something.
  },
  failure: 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"
  }
}