オブジェクトの ID と URI

Kii Cloud では、ユーザー、グループ、KiiObject など、様々なオブジェクトを扱います。

Kii Cloud SDK からこれらのオブジェクトにアクセスする際、KiiUser、KiiGroup、KiiObject などのオブジェクトを認識するため、それぞれ固有の ID と URI が与えられます。ID や URI を使用すると、オブジェクトを一意に識別できます。

以下に ID と URI の例を挙げます。

種類 ID の例 URI の例
KiiUser 01234567-89ab-cdef-0123-456789abcdef kiicloud://users/01234567-89ab-cdef-0123-
456789abcdef
KiiGroup 0123456789abcdefghijklmno kiicloud://groups/0123456789abcdefghijklmno
KiiBucket bucketName －
KiiObject 0123456789ab-cdef-0123-4567-89abcdef
  • アプリケーションスコープ
    kiicloud://buckets/bucketName/objects/0123456789ab-
    cdef-0123-4567-89abcdef
  • グループスコープ
    kiicloud://groups/0123456789abcdefghijklmno/buckets/
    bucketName/objects/0123456789ab-cdef-0123-4567-
    89abcdef
  • ユーザースコープ
    kiicloud://users/01234567-89ab-cdef-0123-
    456789abcdef/buckets/bucketName/objects/
    0123456789ab-cdef-0123-4567-89abcdef
  • Thing スコープ
    kiicloud://things/th.0123456789ab-cdef-0123-4567-
    89abcdef/buckets/bucketName/objects/01234567-
    89ab-cdef-0123-456789abcdef
※Bucket「bucketName」にあるオブジェクトの場合

  • KiiUser、KiiGroup、KiiObject の ID は、それぞれに割り当てられた固有の値であり、それらを一意に識別することができます。

    • KiiObject の ID は設計上「Bucket 内」で一意です。この ID は、Kii Cloud が自動的に振り出すことも、モバイルアプリから指定した ID を使うこともできます。
    • 「アプリケーション内」で KiiObject を一意に識別するには、ID の他に、Bucket 名（Bucket ID）とスコープ（Application、Group インスタンス、User インスタンス、Thing インスタンス）も同時に必要です。一意に表現する場合は、Object ID の代わりに URI の使用が妥当です。一部のクライアント SDK では ID を取得する API を用意していません。また、Object ID を UUID と表現している SDK もあります。

  • Bucket の ID は、モバイルアプリから指定した Bucket の名前を、直接 ID として使用します。また、対応する URI 表現は SDK では使用しません。

  • URI は ID を含む文字列で、アプリケーション内のオブジェクトを一意に識別できます。

  • REST API ではこの表と表現形式が異なり、リクエスト中の URI を使って表現します。

Thing に対する ID の表現はこれらと扱い方が異なります。詳細は Kii Cloud SDK for Thing の機能概要 をご覧ください。

サポートしている操作は以下のとおりです。

種類 新規作成 既存データの操作
ID 指定での作成 ID 自動発行 ID の取得 ID からの生成 URI の取得 URI からの生成
KiiUser － ◯ ◯ ◯ ◯ ◯
KiiGroup ◯ ◯ ◯ ◯ ◯ ◯
KiiBucket ◯※1 － ◯※1 ◯※1 － －
KiiObject ◯ ◯ ◯ ◯ ◯ ◯

※1 REST でいう Bucket ID は クライアント SDK でいう Bucket 名です。

インスタンスと ID/URI との相互変換

クライアント SDK では KiiUser、KiiGroup、KiiBucket、KiiObject を SDK で定義されたクラスのインスタンスとして表現しますが、これらのインスタンスと ID/URI は相互に変換できます。

作成したオブジェクトから ID や URI を取得して文字列の形で保存しておけば、必要なときに、対応するインスタンスをすぐに生成できます。ただし、ID や URI からインスタンスを作成した直後は内容が空になっているため、リフレッシュ操作によって Kii Cloud からコンテンツをダウンロードする必要があります。

ID と URI の両方をサポートする KiiUser と KiiGroup では、内部で ID と URI が相互に変換されます。そのため、たとえば ID によって生成したオブジェクトから、リフレッシュ操作なしで URI を取得することもできます。

ID/URI だけのオブジェクト

クライアント SDK では、API の引数や戻り値として、ID や URI だけが設定された空のオブジェクトを扱うものがあります。ここでの「オブジェクト」は、ユーザー、グループ、KiiObject など、クライアント SDK で扱う一般的な対象物を表します。

ID/URI だけが設定されているオブジェクトでは、オブジェクトから値を取得できませんが、クラウド上のオブジェクトは一意に特定することができます。そのため、ネットワークアクセスを伴う API の引数としてオブジェクトを指定する場合は、ID/URI だけで十分です。

逆に、API からの戻り値として ID/URI だけが設定されたオブジェクトを返すことがあります。オブジェクトのデータにアクセスしたい場合は、クライアント SDK の refresh メソッドなど（プラットフォームごとにメソッド名は多少異なります）を使って、クラウドからオブジェクト内のコンテンツをダウンロードする必要があります。

たとえば、あるグループの URI を持っているとき、そのグループに所属するユーザー名の一覧を取得したいときは、以下のような実装となります。

  1. URI から KiiGroup のインスタンスを作成します。

    作成後のインスタンスは、ID/URI だけの空のオブジェクトです。

  2. KiiGroup のメンバー一覧メソッドを呼び出します。

    URI だけが設定されたグループを引数にして Kii Cloud を呼び出すことができます。

    戻り値として KiiUser の一覧が返りますが、これは ID/URI だけが設定されたユーザーオブジェクトです。

  3. ユーザー名を取得するため、内容を取得します。

    ユーザーごとに refresh メソッドを呼び出す必要があります。実行後、ユーザー名を取得できます。