Object の更新

Object を更新する際、次の 2 通りの方法を選択できます。

フルアップデート
部分アップデート

フルアップデート

Thing から送信されたキーと値のペアで、サーバー上のデータを完全に上書きする方法です。サーバーにあった値は、上書きによって失われます。Object の更新例は、機能ガイドのフルアップデートをご覧ください。

更新のコード例を以下に挙げます。

/* Set KiiObject parameters. */
#define OBJECT_ID "STATUS_TEMPERATURE"
#define OBJECT_REPLACEMENT_DATA "{\"power\":false, \"status\":\"ERROR\"}"
#define OBJECT_ETAG "1"

/* 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";

/* Fully update the KiiObject. */
ret = kii_object_replace(&kii, &bucket, OBJECT_ID, OBJECT_REPLACEMENT_DATA, OBJECT_ETAG);
if (ret != 0) {
  /* Handle the error. */
  return;
}

取得対象の Bucket は、kii_bucket_t 構造体で指定します。指定方法は、Object の作成をご覧ください。

最後の引数値 OBJECT_ETAG は、楽観的ロックによる更新チェックを行う場合に指定します。

NULL を指定した場合：

引数が NULL の場合は楽観的ロックによる更新チェックは行いません。指定した JSON の値で上書きが行われます。
NULL 以外の値を指定した場合：

NULL 以外の値を指定した場合は楽観的ロックによる更新チェックを行います。Kii Cloud は、指定した値とサーバー側の Object の _version フィールドの値を比較し、同じ値の場合にだけ更新を行います。呼び出し元から指定する値は、この Thing で前回この Object を読み込んだときの _version フィールドの値です。

前回 Thing が Object を読み込んだ後、他のクライアントから Object が更新されると、サーバーでは自動的に _version フィールドの値がインクリメントされます。このため、Thing から指定した値とサーバー側の Object の _version フィールドの値が不一致となります。Kii Cloud は更新の衝突が起こっていると判定し、Object の更新を拒否します。

部分アップデート

Thing から送信されたキーと値のペアと、サーバー上の既存のキーと値のペアをサーバー上でマージして更新する方法です。変更の差分だけを JSON として呼び出し元で用意して、サーバーに送信します。Object の更新例は、機能ガイドの部分アップデートをご覧ください。なお、サーバー側のキーそのものはこの方法で削除できません。

更新のコード例を以下に挙げます。

/* Set KiiObject parameters. */
#define OBJECT_ID "STATUS_TEMPERATURE"
#define OBJECT_REPLACEMENT_DATA "{\"power\":false, \"status\":\"ERROR\"}"
#define OBJECT_ETAG "1"

/* 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";

/* Partially update the KiiObject. */
ret = kii_object_patch(&kii, &bucket, OBJECT_ID, OBJECT_REPLACEMENT_DATA, OBJECT_ETAG);
if (ret != 0) {
  /* Handle the error. */
  return;
}

パラメーターの指定方法は、フルアップデートの場合と同じです。

安全な更新の観点としては、これ以外に、複数 Object の更新中のエラーへの配慮が必要になる場合があります。詳細はトランザクションを参照してください。