Object の作成

Object を作成するには、格納したい JSON データを文字列の形式で指定して API を呼び出します。Object の格納先の Bucket は、任意のスコープを指定できます。ただし、格納先 Bucket に対する Object 追加の権限を Thing が有している必要がある点に注意してください。

Bucket は、最初の Object を作成する際、自動的に作成されます。

Object の作成は、ID を Kii Cloud で自動的に発行する方法と、Thing 上のプログラムで ID を指定する方法の 2 通りをサポートしています。

ID を自動発行して Object を作成

Object を作成するサンプルコードを以下に示します。

/* Set KiiObject parameters. */
#define OBJECT_DATA "{\"power\":true, \"temperature\":25, \"status\":\"NORMAL\"}"
#define CONTENT_TYPE NULL

char object_id[KII_OBJECTID_SIZE + 1];

int ret;

/* Set bucket parameters. */
kii_bucket_t bucket;
memset(&bucket, 0x00, sizeof(kii_bucket_t));
bucket.scope = KII_SCOPE_THING;
bucket.bucket_name = "myBucket";
bucket.scope_id = "VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS";

/* Create a KiiObject. */
ret = kii_object_create(&kii, &bucket, OBJECT_DATA, CONTENT_TYPE, object_id);
if (ret != 0) {
  /* Handle the error. */
  return;
}

printf("object ID:%s\n", object_id);

Object を作成する Bucket は kii_bucket_t 構造体で指定します。設定方法を以下に示します。

今回のサンプルコードでは、Thing スコープにある myBucket という Bucket を指定しています。この例では、vendorThingID rBnvSPOXBDF9r29GJeGS によって アクセストークンを取得 し、kii_t を初期化している状態を想定しています。kii_bucket_t 構造体の scope_id メンバーでは、VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS というスコープ ID を指定しているため、アクセストークンを持っている Thing の Thing スコープにある Bucket に Object を作成します。

kii_object_create 関数を呼び出すと、Kii Cloud との通信が行われ、OBJECT_DATA で指定した JSON 文字列を持った Object が作成されます。関数からは、Object の ID が object_id に返されます。

格納できるデータの最大サイズは JSON 形式で表現した状態で Unicode 換算で 65534 文字までです（サイズには Kii Cloud が内部で使用するフィールドも含まれます）。

kii_object_create の第 4 引数は、Object のメディアタイプを指定します。Object のメディアタイプには "application/json" か "application/vnd.{APPID}.{DATATYPE}" が指定できます。後者の場合、{DATA_TYPE} には任意の値が利用可能です。省略する場合は NULL を指定できます。

Object アクセスのヒント

• 書き込んだはずの Object が参照できない：

  Bucket のスコープが意図したとおりかどうか、ご確認ください。

  書き込みと読み込みを異なるスコープで行うと、Bucket 名が同じであっても書き込んだ内容を取得できません。開発者ポータルのデータブラウザを使って読み込んだ場合でも、同様です。

  たとえば、アプリケーションスコープの myBucket に作成したデータは、ユーザースコープの myBucket から読み込もうとしても、結果が得られません。

Bucket 一覧機能の実装ヒント

Bucket 一覧の機能が必要な場合、アプリ側での実装が必要となります。

通常、Bucket は Bucket 名を使ってプログラムから固定的にアクセスするため、一覧が必要となるケースはあまりないはずです。動的に Bucket を生成するような特殊なケースで一覧が必要な場合は、アプリケーションスコープに Bucket 名の一覧の情報を格納するなどの方法をとれます。実装方法は、ユーザー一覧の実装方法 を参考にしてください。

位置情報の利用

位置情報を保存するためのデータタイプとして GeoPoint が利用できます。GeoPoint の指定方法は、REST API での説明をご覧ください。

なお、GeoPoint は JSON のデータ表現だけの機能ではなく、指定した地点からの距離や範囲での検索機能をサポートしています。検索機能の利用方法は、REST API の KiiObject の検索 をご覧ください。

ID を指定して Object を作成

明示的に ID を指定して Object を作成することもできます。

以下に、Object を ID を指定して作成する例を挙げます。

/* Set KiiObject parameters. */
#define OBJECT_ID "STATUS_TEMPERATURE"
#define OBJECT_DATA "{\"power\":true, \"temperature\":25, \"status\":\"NORMAL\"}"
#define CONTENT_TYPE NULL

int ret;

/* Set bucket parameters. */
kii_bucket_t bucket;
memset(&bucket, 0x00, sizeof(kii_bucket_t));
bucket.scope = KII_SCOPE_THING;
bucket.bucket_name = "myBucket";
bucket.scope_id = "VENDOR_THING_ID:rBnvSPOXBDF9r29GJeGS";

/* Create a KiiObject. */
ret = kii_object_create_with_id(&kii, &bucket, OBJECT_ID, OBJECT_DATA, CONTENT_TYPE);
if (ret != 0) {
  /* Handle the error. */
  return;
}

kii_object_create_with_id 関数の第 3 引数で Object の ID を指定します。ここでは、STATUS_TEMPERATURE という固定の ID を指定して Object を作成しています。使用可能な ID のパターンについては Kii Cloud SDK for Android の Javadoc を参考にしてください。

その他のパラメーターの指定方法は、kii_object_create 関数と同様です。