JSON ドキュメントのアクセス
KiiObjectでは、JSON ドキュメントをキーと値のペアとして設定または取得できます。
Kii Cloud SDK で書き込まれた値は、クラウド上では JSON 形式で保存されます。Kii Cloud SDK のメソッドを通して値を設定すると、指定したキーは、JSON の第 1 階層として保存されます。読み込み時には、JSON 形式のデータの第 1 階層以降を Kii Cloud SDK からキーと値のペアとして読み込みます。
REST API を使用する場合は、JSON 形式の文字列をリクエストやレスポンスのデータとして直接扱います。
たとえば、2 つのクライアントの間でデータを共有する場合、JSON ドキュメントを通して、以下のようにキーと値のペアにアクセスします。保存したデータを同じクライアントから読み直すような場合も同様です。
KiiObject の保存は JSON 形式で行われるため、図の「クライアント 1」と「クライアント 2」は、たとえプラットフォームが違っていても、アクセスする際の型が合っていれば設定した値を正しく読み込むことができます。
JSON の第 1 階層に格納された値は、自動的にインデックスの作成対象となります。KiiObject の検索 では、このインデックスを使って条件に一致する KiiObject を高速に取得することができます。なお、第 2 階層以下の深い階層にある値は検索できません。
キーと値のペア
キーと値のペアに格納できるキーには、予約済みの所定キーと、アプリケーションで自由に使用できる任意キーがあります。
所定キー
所定キーは Kii Cloud で予約されているキーです。キー名が "_"（アンダースコア）で始まるものが所定キーで、アプリケーションから別の目的で使用できません。
以下の所定キーは、KiiObject の作成や更新のタイミングで自動的に作成または更新されます。所定キーは Kii Cloud の内部処理で使用される他、JSON ドキュメントの取得 や KiiObject の検索 でも使用できます。
| キー名 | 内容 |
|---|---|
| _id | KiiObject の識別子（KiiObject ID）です。自動的に割り当てられた値か、作成時に指定した値のどちらかになります。ID の値は Bucket 内だけで一意であることが保証されます。 |
| _owner | KiiObject を作成したユーザーを表す識別子（User ID）です。特に Object の ACL で使用されます。 |
| _created | KiiObject の作成日時（UNIX 時間、ミリ秒、UTC）です。 |
| _modified | KiiObject の最終更新日時（UNIX 時間、ミリ秒、UTC）です。作成直後は _created と同じ値です。 |
| _dataType | KiiObject のデータタイプです。KiiObject を作成した際に明示的に指定した場合は、この値が設定されます。特に Object Body の公開 で使用されます。 |
| _bodyType | Object Body のデータタイプです。Object Body をアップロードした際に指定した値が設定されます。 |
| _version | KiiObject のバージョン番号です。作成直後は 1 で、更新するたびに 1 ずつ増えます。更新の衝突が発生したことを検出するために、楽観的ロック で使用します。 |
任意キー
任意キーはアプリケーションで自由に使用できるキーです。所定キーで予約されているキー名以外の名前を自由に使用できます。
値のデータ型は、JSON のデータ形式に変換できる任意の型を使用できます。数値や文字列の他、JSON の配列や JSON オブジェクトなどのデータ型も扱うことができます。また、位置情報 も 1 つのデータ型として定義されています。
キーと値のペアが Kii Cloud に書き込まれる際、サーバー上では（Bucket, キー, 値）によるインデックスが自動的に生成されます。インデックスは、KiiObject の検索を行う際に利用されます。
なおインデックスは、キーの長さが250文字までの場合、および値が文字列の場合は190文字までの場合に生成されます。これらの条件を満たさないキーと値のペアではインデックスが生成されないため、そのキーを使った検索はできません。