本文へジャンプします。

ニフクラ ユーザーガイド

クラウド トップ>ユーザーガイド>IoTデバイスハブ>ホームにキーバリューペアを保存する

ホームにキーバリューペアを保存する

IoTデバイスハブのプロジェクトにアプリを作成するとき、ある種のキーバリューストレージが必要になることがあります。特にホームに所属するメンバー全員が共有できる永続的なデータストレージが必要な場合があります。例えば、そのホームの地理位置情報などのメタデータを保存したり、ホームに所属するデバイスから収集したデータを、集約して保存する場合があるかもしれません。

そのようなデータストアを自分で実装して運用する代わりにIoTデバイスハブを利用すれば、データを保存するだけで済みます。IoTデバイスハブのAPIでホームの情報をキーバリューペアとして、保存できます。また、本機能はIoTデバイスハブのネイティブ機能であり、プロジェクトの設定を有効化または更新する必要はありません。

キーバリューストア API

REST APIでは、あるホームのキーバリューストアは、次のようなリソースで表されます。

/homes/{homeId}/kv

このAPIリソースは、適切なAPIキーを持つ呼び出し元に限定されています。適切なAPIキーとは下記を指します。

デフォルトでは、プロジェクトのAPIキーは、キーバリューストアへの読み取り専用のアクセス権限しか与えられていません。プロジェクトのAPIキーを使用して、キーバリューペアを作成または更新する場合には、コントロールパネルのプロジェクトの設定でキーの権限設定を変更する必要があります。

キーバリューストア API

キーバリューストアへの書き込み

あるキーバリューペアは、API エンドポイントから下記の形式で呼び出すことができます。

/homes/{homeId}/kv/{key}

keyはhomeIdで指定されたホーム内でユニークでなければなりません。
キーには英数字・アンダースコア(_)・ダッシュ(-)を含むことができ、最初と最後の文字は英数字にする必要があります。以下に何点か例を挙げます。

  • avgTemp
  • value5
  • room5_device_count

ホームにキーバリューペアを保存するには、所定のエンドポイントにPUTリクエストを送ります。例えば、以下のようになります。

 $ curl -i -X PUT -H "Authorization: ModeCloud _YOUR_API_KEY_" -H "Content-Type: application/json" -d "{\"value\": 123}" https://iot-device.jp-east-1.api.cloud.nifty.com/homes/HOME_ID/kv/foo

ここでは、HOME_IDのホームでfooというキーに123という値を割り当てています。この例では値が数値ですが、文字列・真偽値・配列・オブジェクトも割り当てることができます。唯一許可されていないデータタイプはnullです。
キーバリューストアの作成も更新も同じAPIの呼び出しで行います。キーがホームにまだ存在しない場合、作成されます。存在していた場合には、キーの値が新しい値で上書きされます。

キーバリューストアからの読み出し

キーバリューペアを読み出すには、単純にエンドポイントへGETリクエストを送ります。例えば、以下のようになります:

 $ curl -i -H "Authorization: ModeCloud _YOUR_API_KEY_" https://iot-device.jp-east-1.api.cloud.nifty.com/homes/HOME_ID/kv/foo

対応するキーバリューペアのJSONオブジェクトが返却されます。

 {"key":"foo","value":123,"modificationTime":"2016-12-29T23:30:45.022Z"}

ホームに存在するすべてのキーバリューペアを取得するには、下記のようにキーバリューストアエンドポイントへGETリクエストを送ります。

 $ curl -i -H "Authorization: ModeCloud _YOUR_API_KEY_" https://iot-device.jp-east-1.api.cloud.nifty.com/homes/HOME_ID/kv

キーバリューペアオブジェクトの配列が返却されます。

キーバリューペアの削除

キーバリューペアを削除するには、エンドポイントへDELETEリクエストを送ります。例えば、以下のようになります。

 $ curl -i -H "Authorization: ModeCloud _YOUR_API_KEY_" -X DELETE https://iot-device.jp-east-1.api.cloud.nifty.com/homes/HOME_ID/kv/foo

システム生成イベント

ユーザー(またはプロジェクトのAPIキーを利用したプログラム)がホームのキーバリューペアを変更すると、ほかの関係するコンポーネントがその変更について、知ることができます。例えば、ホームのほかのメンバーが利用しているアプリについて、キーバリューペアの変更が発生した際にアプリの内部状態も自動的に更新したい場合があるかもしれません。そのような場合には、いつでも以下の特別なシステム生成イベントを利用することができます。キーバリューストアによって自動的に発行されるイベントです。

_keyValueSaved_ キーバリューペアが作成または更新されたときに発行されます。イベントデータは、対象のキーバリューを示すために、`key`フィールドと`value`フィールドを含みます。
_keyValueDeleted_ キーバリューペアが削除されたときに発行されます。イベントデータは、削除されたキーバリューペアを示すために、`key`フィールドを含みます。

アプリとスマートモジュールから見ると、このようなシステムが生成するイベントは、デバイスやクライアント・プログラムが発行するイベントと同じです。しかし、原則として、イベントタイプ名の最初と最後の文字がアンダースコア(_)であるイベントは、IoTデバイスハブのシステムが生成したイベントであると想定すべきです。

推奨画面サイズ 1024×768 以上