Object Storage

Object Storage は Bucket 内に KiiObject としてデータを保存する機能です。

ここでは モバイル向け機能 の内容を理解している前提で、その詳細について説明します。

KiiObject の内部には、キーと値のペアと Object Body(ファイル)1 件を格納することができます。SDK でオブジェクトを扱うときはキーと値のペアの部分を主体に扱います。Object Body 部分が必要になった場合は、そのオブジェクトに対するアップロード/ダウンロード機能として、キーと値のペアの部分とは別に操作します。

キーと値のペア、Object Body はいずれも必要時のみ扱うことができます。たとえば設定値のようなオブジェクトは Object Body が不要であるため、キーと値のペアだけでオブジェクトを作成できます。Object Body だけを扱うこともできますが、下記の「所定キー」に示すように既定のキーと値が自動的に挿入されます。

キーと値のペア

キーと値のペアは一般的な連想記憶と同様の構造です。オブジェクト中にキー名と値の組を複数個格納して、キー名に対応する値を参照できるようにした格納領域です。最終的に、キーと値のペアは JSON 表現となって Kii Cloud 上に格納されます。

キーと値のペアに格納できるキーには、予約済みの所定キーと、アプリケーションで自由に使用できる任意キーがあります。

所定キー

所定キーは Kii Cloud で予約されているキーです。キー名が "_"(アンダースコア)で始まるものが所定キーで、アプリケーションから別の目的で使用できません。

以下の所定キーは、Object の作成や更新のタイミングで自動的に作成または更新されます。

キー名 内容
_id Object の識別子(Object ID)です。自動的に割り当てられた値か、作成時に指定した値のどちらかになります。ID の値は Bucket 内だけで一意であることが保証されます。詳細は、「オブジェクトの ID と URI」(AndroidiOSJavaScriptUnity)をご覧ください。
_owner Object を作成したユーザーを表す識別子(User ID)です。特に Object の ACL で使用されます。
_created Object の作成日時(UNIX 時間、ミリ秒、UTC)です。
_modified Object の最終更新日時(UNIX 時間、ミリ秒、UTC)です。作成直後は _created と同じ値です。
_dataType Object のデータタイプです。Object を作成した際に明示的に指定した場合は、この値が設定されます。
_bodyType Object Body のデータタイプです。Object Body をアップロードした際に指定した値が設定されます。
_version Object のバージョン番号です。作成直後は 1 で、更新するたびに 1 ずつ増えます。更新の衝突が発生したことを検出するために、楽観的ロック で使用します。

任意キー

任意キーはアプリケーションで自由に使用できるキーです。所定キーで予約されているキー名以外の名前を自由に使用できます。

Value のデータ型は以下のものが利用可能です。

  • String
  • Boolean
  • Int
  • Long
  • Double
  • Byte Array
  • JSON
  • JSON Array
  • GeoPoint(位置情報)

通常、値の格納と取得では同じデータ型を指定します。他のプラットフォームとの間で値をやりとりする場合や、型の変換を伴うアクセスを行う場合は キーと値のペアのデータ変換 をご覧ください。

キーと値のペアが Kii Cloud に書き込まれる際、サーバー上では(Bucket, Key, Value)によるインデックスが自動的に生成されます。インデックスは、Object の検索を行う際に利用されます。

なおインデックスは、キーの長さが250文字までの場合、および値が文字列の場合は190文字までの場合に生成されます。これらの条件を超えた場合、Object に対するインデックスは生成されません(このキーで検索した際、Object は検索対象外となります)。

Object Body

ファイルなどの大きなデータを KiiObject に紐付けて管理することができます。このデータのことを Object Body と呼びます。

たとえば、ある動画に関するメタデータをキーと値のペアとして KiiObject に保存しつつ、実際の動画ファイルは Object Body としてこの KiiObject に紐付けた形で Kii Cloud に保存することができます。

Object Body をサポートしないプラットフォームもありますが、それらのプラットフォームでも、Object Body を持った KiiObject のキーと値のペアを更新することは可能です。その場合、Object Body は元の状態を保持し続けます。

Object Body のサイズは大きいため、次のような点が考慮されています。

  • Kii Cloud 内ではキーと値のペアと Object Body を 1 つの KiiObject として認識できますが、API ではキーと値のペアと Object Body は別に扱います。

    • クライアント SDK では、Object Body はリクエスト時にのみファイルとして読み書きします。
    • REST では、通常のキーと値のペアの取得機能とは別に Object Body を独立して取得する API を用意しています。
  • 転送中のファイルの中断と再開をサポートするプラットフォームがあります。大きいファイルの転送を一旦中断し、次回、その続きを転送することができます。

Object Body は 1 つの KiiObject に対して 1 件だけ格納することができます。複数の Object Body を格納することはできません。

たとえば、KiiObject ごとに複数のアイコンを持つような場合、Object Body の代わりに BASE64 等のデータとしてキーと値のペアで保存する設計も選択できます。この場合、キーと値のペアの JSON 形式での表現がサイズ上限の 64 KB を超えるとエラーになります。逆に、サイズが限定されるような場合、キーと値のペアとして格納しておくと、KiiObject のクエリーによって他のデータと BASE64 データを同時に取得できるメリットもあります。