キーと値のペアのデータ変換

Kii Cloud に保存されている KiiObject を複数のプラットフォームで読み込むときは、データの変換方法についての知識が必要です。ここではキーと値のペアで使用するデータ形式について、JSON のデータ形式とクライアント SDK での値の変換方法を説明します。

特定のプラットフォームで、かつ、決められた型でしか値を読み書きしない場合(int で書き込んだ値は、必ず int で取得する場合など)、このページの内容はご覧にならなくても問題ありません。

KiiObject のキーと値のペアは、最終的に JSON 形式で Kii Cloud に格納されます。格納された値はクライアント SDK から読み込みと書き込みができますが、その際には JSON 形式の文字列と set/get API との間で一定の変換ルールがあります。

図のように、クライアント SDK のメソッドを通して値を設定すると、JSON の第 1 階層に保存されます。このとき、JSON でのデータの型、または、JSON から戻り値として取得される変数の型は、以下に示すルールによって決まります。

Android

設定

  • データ型ごとに set メソッドが用意されており、そのメソッドに基づいて JSON 文字列での型が決まります。

  • Byte Array の設定では指定された値を BASE64 で変換した結果を JSON の文字列値として書き込みます。

実際の設定例は下記のとおりです。メソッドの種類に応じて JSON の型が決まります。

呼び出すメソッド JSON での値の例 備考
メソッド名 引数
setBoolean()truetrue
setByteArray()61,61,61,61(aaaa)"YWFhYQ==\n"BASE64 エンコードした値です。
setDouble()123.456123.456
setInt()123123
setJsonArray()[1,2,3][1,2,3]
setJsonObject(){"a":"b"}{"a":"b"}
setLong()123123
setString()"123""123"文字列のため、JSON では " " で囲まれます。
setUri()"http://www.kii.com/""http://www.kii.com/"

※値として null を設定する方法はありません。設定すると無視またはエラーとなります。

取得

  • モバイルアプリ側で取得したい型ごとに get メソッド(getStringgetInt など)が提供されています。JSON の型が取得したいデータ型に変換できない場合は例外が発生します。

  • キーが存在しない場合は例外が発生します。

  • JSON で null が設定されている場合、null を表現できる String 等の型では null として取得できます。int 等の null がない型では取得で例外が発生します。

  • 目的の型に変換可能なデータはそのまま取得できます。たとえば、文字列として格納された数値( {"data":"20"}"20" など)を int として取り出したり、JSON オブジェクトを String として取り出したりすることができます。ただし、文字列の一部を数値として取り出すことはできません("123x456"123 と解釈されません)。

  • 数値の取得でオーバーフローが発生した場合は 0 が返ります(Unity と異なる動作です)。

  • Byte Array の取得では、JSON の文字列データのうち BASE64 と解釈可能な部分のみを利用して byte[] に変換します。たとえば {"a":"b"} は BASE64 ab== として解釈し、69 がデコードされます。

実際の取得例を以下に示します。以下の表は次のような JSON オブジェクトを取得した場合の動きです。

{
  "value1": "abc",
  "value2": "123",
  "value3": "123x456",
  "value4": {"a":"b"},
  "value5": null,
  "value6": [1, 2, 3],
  "value7": 123,
  "value8": 8589934592,
  "value9": 456.789,
  "value10": true
}
メソッドvalue1value2value3value4value5
"abc""123""123x456"{"a":"b"}null
getBoolean()例外例外例外例外例外
getByteArray()69, b7d7,6dd7,6d,f1,e3,9e6993,e9,65
getDouble()例外123.0例外例外例外
getInt()例外123例外例外例外
getJsonArray()例外例外例外例外例外
getJSONObject()例外例外例外{"a":"b"}例外
getLong()例外123例外例外例外
getString()abc123123x456{"a":"b"}null
getUri()abc123123x456{"a":"b"}null
getGeoPoint()例外例外例外例外例外

(続き)

メソッドvalue6value7value8value9value10
[1,2,3]1238589934592456.789true
getBoolean()例外例外例外例外true
getByteArray()d7,6dd7,6df3,9f,3d,f7,7e,39,f7e3,9e,bb,f3b6,bb,9e
getDouble()例外123.08.589934592E9456.789例外
getInt()例外1230456例外
getJsonArray()[1,2,3]例外例外例外例外
getJSONObject()例外例外例外例外例外
getLong()例外1238589934592456例外
getString()[1,2,3]1238589934592456.789true
getUri()[1,2,3]1238589934592456.789true
getGeoPoint()例外例外例外例外例外
※ 黄色い背景の箇所が本来の読み込み方法です。

iOS

iOS では、扱うデータ型が文字列や数値などの通常のデータか、GeoPoint(位置情報)かによって呼び出す API が異なります。GeoPoint の設定と取得は、専用のセレクタを使用します。以下は、GeoPoint 以外の通常のデータ型について示します。

設定

API から値を設定するときは、引数の変数の型に基づいて JSON での型が決まります。たとえば、NSNumber の 123 をキーscore に書き込むと数値データ {"score":123} となりますが、NSString の @"123" を書き込むと文字列データ {"score":"123"} となります。

JSON の null を設定することはできません。

取得

下記 GeoPoint 以外のデータは、JSON の型に応じて NSString、int、BOOL、key/value pair、NSArray などを保持する id 型で返します。リファレンスガイドのサンプルコードをご覧ください。

キーが存在しない場合は nil を、JSON の値として null が格納されている状態では NSNull を返すため、これらを区別することができます。

設定と取得を行った場合の動作は以下のとおりです。上記の Android の例と同じ JSON を扱う場合の動作を記載しています。

JSON での値 setObject に渡す値 または getObjectForKey の結果 備考
"abc" abc(NSString)
"123" 123(NSString)
"123x456" 123x456(NSString)
{"a":"b"} {a=b}(NSDictionary)
null NSNull。設定は不可
[1,2,3] {1,2,3}(NSArray)
123 123(NSNumber) 取得時はサブクラスの NSDecimalNumber です。
8589934592 8589934592(NSNumber) 取得時はサブクラスの NSDecimalNumber です。
456.789 456.789(NSNumber) 取得時はサブクラスの NSDecimalNumber です。
true YES(NSBoolean)
存在しないキー nil 取得時の動作

JavaScript

JSON は JavaScript のオブジェクトの表記法がベースとなっているため、基本的に JavaSciprt のデータ型がそのまま JSON の文字列に変換されます。

SDK では、GeoPoint(位置情報)の取得と設定のみ、専用のメソッドを用意しています。それ以外は JavaScript の型との間で直接変換します。

設定

API から値を設定するときは、引数の型に基づいて型が決まります。たとえば、数値の 123 をキー score に書き込むと数値データ {"score":123} となりますが、文字列の "123" を書き込むと文字列データ {"score":"123"} となります。

取得

JSON のデータ型に対応する値が取得できます。たとえば、数値データ {"score":123} は数値型 123 となりますが、文字列データ {"score":"123"} は文字列の "123" として取得されます。

キーが存在しない場合は undefined を、JSON の値として null が格納されている場合は null を返すため、これらを区別することができます。

Unity

Unity では、扱うデータ型が文字列や数値などの通常のデータか、GeoPoint(位置情報)かによって呼び出す API が異なります。GeoPoint の設定と取得は、専用のメソッドを使用します。以下は、GeoPoint 以外の通常のデータ型について示します。

設定

Unity ではインデクサ(C# の [ ])によって値を設定します。インデクサで値を設定するときは、引数の変数の型に基づいて型が決まります。たとえば、int の 123 をキー score に書き込むと数値データ {"score":123} となりますが、string の "123" を書き込むと文字列データ {"score":"123"} となります。

null を設定することはできません。

取得

API から値を取得するときは、次の 2 通りの方法を選択できます。

  • インデクサによる取得

    インデクサ(C# の [ ])によって値を取得できます。たとえば、obj から score キーの値を取得する場合、obj["score"] のようなコードになります。

    戻り値は JSON の型表現に応じて Int32、String 等の型で戻ります。

    JSON にキーがない場合は例外になります。値が null の場合は JsonNull を返します。

  • 型に応じた Get メソッドによる取得

    • モバイルアプリ側で取得したい型ごとに Get メソッド(GetStringGetInt など)を用意しています。JSON の型が取得したいデータ型に変換できない場合は例外が発生します。
    • キーが存在しない場合は例外が発生します。
    • JSON で null が設定されている場合、null を表現できる String 等の型では null として取得します。int 等の null がない型では取得で例外が発生します。
    • 目的の型に変換可能なデータはそのまま取得できます。たとえば、文字列として格納された数値("data":"20" など)を int として取り出したり、JSON オブジェクトを string として取り出したりすることができます。ただし、文字列の一部を数値として取り出すことはできません("123x456"123 と解釈されません)。
    • 数値の取得でオーバーフローが発生した場合は例外が発生します(Android と異なる動作です)。

実際の取得例を以下に示します。以下の表は Android の説明に示した JSON オブジェクトを取得した場合の動きです。

メソッドvalue1value2value3value4value5
"abc""123""123x456"{"a":"b"}null
インデクサabc (String)123 (String)123x456 (String){"a":"b"} (JsonObject)null (JsonNull)
GetBoolean()例外例外例外例外例外
GetByteArray()※1例外例外例外例外9e,e9,65
GetDouble()例外123例外例外例外
GetGeoPoint()例外例外例外例外例外
GetInt()例外123例外例外例外
GetJsonArray()例外例外例外例外例外
GetJsonObject()例外例外例外{"a":"b"}例外
GetLong()例外123例外例外例外
GetString()abc123123x456{"a":"b"}null
GetUri()例外例外例外例外例外

(続き)

メソッドvalue6value7value8value9value10
[1,2,3]1238589934592456.789true
インデクサ[1,2,3](JsonArray)123 (Int32)8589934592 (Int64)456.789 (Double)true (Boolean)
GetBoolean()例外例外例外例外True
GetByteArray()※1例外例外例外例外4e,bb,9e
GetDouble()例外例外例外456.789例外
GetGeoPoint()例外例外例外例外例外
GetInt()例外123例外例外例外
GetJsonArray()[1,2,3]例外例外例外例外
GetJsonObject()例外例外例外例外例外
GetLong()例外1238589934592457※2例外
GetString()[1,2,3]1238589934592456.789True
GetUri()例外例外例外例外例外

※ 黄色い背景の箇所が本来の読み込み方法です。

REST

REST では JSON 文字列を直接扱います。プラットフォームをまたいで値をやりとりする場合は、REST 以外の環境での設定方法を考慮します。