キーと値のペアの設定

KiiObject にキーと値のペアを設定するには、KiiObject クラスの setObject(forKey:) メソッドを呼び出します。setObject(forKey:) メソッドは格納する型ごとにオーバーロードされたメソッドを用意しています。

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

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

Swift:

let object = bucket.createObject()
object.setObject(NSNumber(integerLiteral: 987), forKey: "score")
object.setObject("easy", forKey: "mode")
object.setObject(NSNumber(booleanLiteral: false), forKey: "premiumUser")

Objective-C:

KiiObject *object = [bucket createObject];
[object setObject:[NSNumber numberWithInt:987]
           forKey:@"score"];
[object setObject:@"easy"
           forKey:@"mode"];
[object setObject:[NSNumber numberWithBool:NO]
           forKey:@"premiumUser"];

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

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

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

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

サポートするデータ型

setObject(forKey:) メソッドの値部分は、NSString、NSNumber、NSArray、NSDictionary のいずれかの型を指定できます。

Kii Cloud に格納できる数値の範囲には制限がないため、NSNumber がサポートする様々な型の最大値を格納することができます。以下の表には Int、Bool、Double の例を示していますが、イニシャライザ NSNumber(value:) によって、Int16 や Float などの他の型を扱うこともできます。

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

Swift:

値の型	呼び出し例	JSON での値の格納結果	備考
NSString	`object.setObject("123", forKey: "data");`	`"data":"123"`
NSNumber(Int)	`object.setObject(NSNumber(integerLiteral: 123), forKey: "data");`	`"data":123`
NSNumber(Int64)	`object.setObject(NSNumber(value: 123 as Int64), forKey: "data");`	`"data":123`
NSNumber(Double)	`object.setObject(NSNumber(floatLiteral: 123.456), forKey: "data");`	`"data":123.456`
NSNumber(Bool)	`object.setObject(NSNumber(booleanLiteral: true), forKey: "data");`	`"data":true`	NSNumber でも Bool を設定済みの場合は true/false を格納
KiiGeoPoint	`object.setGeoPoint(geoPoint, forKey: "data");`	`"data":{` `"_type": "point",` `"lat": 35.658603,` `"lon": 139.745433` `}`	`geoPoint` が (35.658603, 139.745433) の場合
NSArray	`object.setObject(array, forKey: "data");`	`"data":[1,2,3]`	`array` が [1,2,3] の場合
NSDictionary	`object.setObject(json, forKey: "data");`	`"data":{"a":"b"}`	`json` が {"a":"b"} の場合

Objective-C:

値の型	呼び出し例	JSON での値の格納結果	備考
NSString	`[object setObject:@"123" forKey:@"data"];`	`"data":"123"`
NSNumber(int)	`[object setObject:[NSNumber numberWithInt:123] forKey:@"data"];`	`"data":123`
NSNumber(long long)	`[object setObject:[NSNumber numberWithLongLong:123] forKey:@"data"];`	`"data":123`
NSNumber(double)	`[object setObject:[NSNumber numberWithDouble:123.456] forKey:@"data"];`	`"data":123.456`
NSNumber(BOOL)	`[object setObject:[NSNumber numberWithBool:YES] forKey:@"data"];`	`"data":true`	NSNumber でも BOOL を設定済みの場合は true/false を格納
KiiGeoPoint	`[object setGeoPoint:geoPoint forKey:@"data"];`	`"data":{` `"_type": "point",` `"lat": 35.658603,` `"lon": 139.745433` `}`	`geoPoint` が (35.658603, 139.745433) の場合
NSArray	`[object setObject:array forKey:@"data"];`	`"data":[1,2,3]`	`array` が [1,2,3] の場合
NSDictionary	`[object setObject:json forKey:@"data"];`	`"data":{"a":"b"}`	`json` が {"a":"b"} の場合

値として null を設定する方法はありません。設定すると無視またはエラーとなります。
日付型（NSDate）を設定したい場合、timeIntervalSince1970 プロパティが返した Double 型の値を 1000 倍することにより、1970 年 1 月 1 日 00:00:00 UTC からのミリ秒数として格納すれば扱いが簡単になります。
iOS では Android にある、バイト配列を BASE64 にして出力する機能はサポートしていません。

基本データ型の設定

KiiObject の新規作成時に、NSString、Int、Double、Bool の各データ型を格納する例を以下に示します。

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

Swift:

// Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Set key-value pairs.
object.setObject("my value", forKey: "stringValue")
object.setObject(NSNumber(integerLiteral: 123), forKey: "intValue")
object.setObject(NSNumber(value: UInt64(Date().timeIntervalSince1970 * 1000)), forKey: "longValue")
object.setObject(NSNumber(floatLiteral: 987.654), forKey: "doubleValue")
object.setObject(NSNumber(booleanLiteral: true), forKey: "booleanValue")

do{
  // Save the KiiObject.
  try object.saveSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}

// Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Set key-value pairs.
object.setObject("my value", forKey: "stringValue")
object.setObject(NSNumber(integerLiteral: 123), forKey: "intValue")
object.setObject(NSNumber(value: UInt64(Date().timeIntervalSince1970 * 1000)), forKey: "longValue")
object.setObject(NSNumber(floatLiteral: 987.654), forKey: "doubleValue")
object.setObject(NSNumber(booleanLiteral: true), forKey: "booleanValue")

// Save the KiiObject.
object.save { (object : KiiObject?, error : Error?) -> Void in
  if (error != nil) {
    // Handle the error.
    return
  }
}

Objective-C:

NSError *error = nil;

// Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Set key-value pairs.
[object setObject:@"my value"
           forKey:@"stringValue"];
[object setObject:[NSNumber numberWithInt:123]
           forKey:@"intValue"];
[object setObject:[NSNumber numberWithLongLong:(long long)([[NSDate date] timeIntervalSince1970] * 1000)]
           forKey:@"longValue"];
[object setObject:[NSNumber numberWithDouble:987.654]
           forKey:@"doubleValue"];
[object setObject:[NSNumber numberWithBool:YES]
           forKey:@"booleanValue"];

// Save the KiiObject.
[object saveSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Set key-value pairs.
[object setObject:@"my value"
           forKey:@"stringValue"];
[object setObject:[NSNumber numberWithInt:123]
           forKey:@"intValue"];
[object setObject:[NSNumber numberWithLongLong:(long long)([[NSDate date] timeIntervalSince1970] * 1000)]
           forKey:@"longValue"];
[object setObject:[NSNumber numberWithDouble:987.654]
           forKey:@"doubleValue"];
[object setObject:[NSNumber numberWithBool:YES]
           forKey:@"booleanValue"];

// Save the KiiObject.
[object saveWithBlock:^(KiiObject *object, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }
}];

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

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

位置情報（GeoPoint）の設定

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

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

例として、アプリケーションスコープに存在する "MyBucket" という Bucket 内に KiiObject を作成し、これに位置情報を 2 つセットするサンプルコードを以下に挙げます。

Swift:

// Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Create GeoPoint objects.
let point1 = KiiGeoPoint(latitude: 35.658603, andLongitude: 139.745433)
let point2 = KiiGeoPoint(latitude: 35.658625, andLongitude: 139.745415)

// Set the GeoPoints to the KiiObject.
object.setGeoPoint(point1, forKey:"location1")
object.setGeoPoint(point2, forKey:"location2")

do{
  // Save the KiiObject.
  try object.saveSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}

// Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Create GeoPoint objects.
let point1 = KiiGeoPoint(latitude: 35.658603, andLongitude: 139.745433)
let point2 = KiiGeoPoint(latitude: 35.658625, andLongitude: 139.745415)

// Set the GeoPoints to the KiiObject.
object.setGeoPoint(point1, forKey:"location1")
object.setGeoPoint(point2, forKey:"location2")

// Save the KiiObject.
object.save { (object : KiiObject?, error : Error?) -> Void in
  if (error != nil) {
    // Handle the error.
    return
  }
}

Objective-C:

NSError *error = nil;

// Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Create GeoPoint objects.
KiiGeoPoint *point1 = [[KiiGeoPoint alloc] initWithLatitude:35.658603
                                               andLongitude:139.745433];
KiiGeoPoint *point2 = [[KiiGeoPoint alloc] initWithLatitude:35.658625
                                               andLongitude:139.745415];

// Set the GeoPoints to the KiiObject.
if (point1) {
  [object setGeoPoint:point1
               forKey:@"location1"];
}
if (point2) {
  [object setGeoPoint:point2
               forKey:@"location2"];
}

// Save the KiiObject.
[object saveSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Create GeoPoint objects.
KiiGeoPoint *point1 = [[KiiGeoPoint alloc] initWithLatitude:35.658603
                                               andLongitude:139.745433];
KiiGeoPoint *point2 = [[KiiGeoPoint alloc] initWithLatitude:35.658625
                                               andLongitude:139.745415];

// Set the GeoPoints to the KiiObject.
if (point1) {
  [object setGeoPoint:point1
               forKey:@"location1"];
}
if (point2) {
  [object setGeoPoint:point2
               forKey:@"location2"];
}

// Save the KiiObject.
[object saveWithBlock:^(KiiObject *object, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }
}];

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

複雑なデータ型の設定

単純なデータ型以外にも、JSON オブジェクトや JSON オブジェクトの配列などのデータ型を SDK でサポートしています。それぞれ、NSDictionary や NSArray などのデータ型に対応します。

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

Swift:

// Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Set a value of a JSON object.
let jsonObject: Dictionary = ["score": 987, "mode": "easy"] as [String : Any]
object.setObject(jsonObject, forKey: "myObject")

// Set a value of a JSON array.
let arrayElement1: Dictionary = ["Name": "Alice", "age": 30] as [String : Any]
let arrayElement2: Dictionary = ["Name": "Bob", "age": 28] as [String : Any]
let jsonArray = [arrayElement1, arrayElement2]
object.setObject(jsonArray, forKey: "myArray")

do{
  // Save the KiiObject.
  try object.saveSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}

// Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Set a value of a JSON object.
let jsonObject: Dictionary = ["score": 987, "mode": "easy"] as [String : Any]
object.setObject(jsonObject, forKey: "myObject")

// Set a value of a JSON array.
let arrayElement1: Dictionary = ["Name": "Alice", "age": 30] as [String : Any]
let arrayElement2: Dictionary = ["Name": "Bob", "age": 28] as [String : Any]
let jsonArray = [arrayElement1, arrayElement2]
object.setObject(jsonArray, forKey: "myArray")

// Save the KiiObject.
object.save { (object : KiiObject?, error : Error?) -> Void in
  if (error != nil) {
    // Handle the error.
    return
  }
}

Objective-C:

NSError *error = nil;

// Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Set a value of a JSON object.
NSDictionary* jsonObject = @{@"score":@987, @"mode":@"easy"};
[object setObject:jsonObject
           forKey:@"myObject"];

// Set a value of a JSON array.
NSDictionary* arrayElement1 = @{@"Name":@"Alice", @"age":@30};
NSDictionary* arrayElement2 = @{@"Name":@"Bob", @"age":@28};
NSArray* jsonArray = @[arrayElement1, arrayElement2];
[object setObject:jsonArray
           forKey:@"myArray"];

// Save the KiiObject.
[object saveSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Set a value of a JSON object.
NSDictionary* jsonObject = @{@"score":@987, @"mode":@"easy"};
[object setObject:jsonObject
           forKey:@"myObject"];

// Set a value of a JSON array.
NSDictionary* arrayElement1 = @{@"Name":@"Alice", @"age":@30};
NSDictionary* arrayElement2 = @{@"Name":@"Bob", @"age":@28};
NSArray* jsonArray = @[arrayElement1, arrayElement2];
[object setObject:jsonArray
           forKey:@"myArray"];

// Save the KiiObject.
[object saveWithBlock:^(KiiObject *object, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }
}];

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

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

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