MENU

Soracom

Users

Harvest Data でデバイスのデータをクラウドで収集・取得・可視化する

このドキュメントでは、Harvest Data を使ってデバイスのデータをクラウドに保存し、そのデータを API で取得する手順を紹介します。また、ユーザーコンソールでデータを可視化する方法も解説します。

当ガイドの前提は以下のとおりです。

  • SORACOM のアカウントを作成済みであること
  • SORACOM Air の SIM (IoT SIM)、および使用できるデバイスが準備されていること

Harvest Data は、設定を有効化すればすぐにデータの収集を始められます。Harvest Data の設定を有効化した状態で、IoT SIM から通信を行っているデバイスまたは LoRa デバイスから、Harvest Data のエントリポイントへデータを送信すると、自動的に送信元の IoT SIM の IMSI とタイムスタンプがデータに付与され、SORACOM のプラットフォーム上にデータが保存されていきます。LoRa デバイスからデータを送信すると、LoRa ゲートウェイ ID 等も自動的に付与されます。

ステップ 1: Harvest Data を有効化する

Harvest Data を有効化するには、ユーザーコンソール、soracom-cli、API のいずれかで設定を行います。

Harvest Data は有料のサービスです。Harvest Data が有効になっていると SIM 1 枚ごとにオプション料金が発生します。詳しくは 料金表 を確認してください。

SORACOM Harvest Data の設定はグループ単位で行います。そのため、Harvest Data を使うには IoT SIM をグループに登録する必要があります。今回は、動作確認として SORACOM Harvest Data 専用のグループを作成し、そのグループに IoT SIM を登録してみましょう。

まず IoT SIM 管理画面を開いて、SORACOM Harvest Data でデータ収集を行いたい IoT SIM にチェックマークを付けます。続いて、[操作] ボタンから [所属グループ変更] を選択します。

IoT SIM の所属グループを選択するためのダイアログが表示されたら、[新しい所属グループ] ドロップダウンから [新しいグループを作成…] を選択します。

以下のようなグループ作成ダイアログが表示されます。グループの名称を入力して [グループ作成] ボタンをクリックします。 今回は"hello harvest"というグループ名で作成してみましょう。

[グループ作成] ボタンを押すと元の [SIM の所属グループ変更] ダイアログに戻ります。 [新しい所属グループ] ドロップボックスが、今作成した hello harvest グループになっていることを確認し [グループ変更] ボタンを押します。

先ほど作成した hello harvest グループに対し、SORACOM Harvest Data の設定を行います。設定を行うためには、グループ管理画面を開き、hello harvest グループを選択してグループ詳細画面を開きます。

[SORACOM Harvest Data 設定] グループの中にあるスイッチを ON に設定し、保存ボタンをクリックしてください。

Harvest Data 設定

SORACOM CLI で設定する場合、soracom groups put-config コマンドで Harvest Data を有効化します。以下のように引数を指定し、コマンドを実行してください。${group_id} の部分は SIM グループの ID に置き換えてください。

$ soracom groups put-config --group-id ${group_id} --namespace SoracomHarvest --body '[{"key":"enabled","value":true}]'

API で設定を有効化するには、putConfigurationParameters API を使って Group Config の一部として設定を入れます。以下のように HTTP PUT リクエストを送信してください。${API-KEY}, ${API-TOKEN} の部分は、ご自身の API 認証情報に置き換えてください。

  • API リクエストを送信する際には API リファレンス も利用できます。利用方法は FAQ を参照してください。
$ curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Soracom-API-Key: ${API-KEY}" \
  -H "X-Soracom-Token: ${API-TOKEN}" \
  -d "[{\"key\":\"enabled\",\"value\":true}]" \
  "https://api.soracom.io/v1/groups/{group_id}/configuration/SoracomHarvest"

ステップ 2: データを送信する

HTTP でデータを送信する場合、Harvest エントリポイント宛に HTTP POST リクエストを送信してください。また、データの種類を content-type で指定してください。

コマンド例:

$ curl -v -X POST \
-H "content-type:application/json" \
-d "{\"temperature\":20}" \
http://harvest.soracom.io

カスタムヘッダ x-soracom-timestamp を付与することで任意のタイムスタンプを指定できます。 x-soracom-timestamp はエポックミリ秒を指定してください。

コマンド例:

$ curl -v -X POST \
-H "content-type:application/json" \
-H "x-soracom-timestamp:1545652714887" \
-d "{\"temperature\":20}" \
http://harvest.soracom.io

TCP, UDP でも HTTP と同様に Harvest エントリポイントにデータを送信してください。簡単にテストするのであれば、telnet コマンドが便利です。

$ telnet harvest.soracom.io 8514
Trying 100.127.xxx.xxx...
Connected to 100.127.xxx.xxx.
Escape character is '^]'.

hello
201
^]

telnet> quit
Connection closed.

送信が成功すると、上記のようにレスポンスコード 201 が返ります。

$ echo "hello" | nc -u -w10 harvest.soracom.io 8514
201

LoRaWAN デバイスを設定する に手順を解説しています。

こちらをご確認ください。


ステップ 3: クラウドに保存されたデータを取得する

IoT SIM で通信しているデバイスから送信されたデータ

データを取得 (ダウンロード)するには、soracom-cli または API を利用します。

soracom-cli では、soracom subscribers get-data コマンドを使います。IoT SIM for Japan のデータを取得する場合には以下のようにコマンドを実行すると、保存されているデータを取得できます。${IMSI} の部分はデータ送信元の IoT SIM の IMSI に置き換えてください。

$ soracom subscribers get-data --imsi ${IMSI}  --coverage-type jp

以下のように API エンドポイントに対して GET リクエストを送信します。データ取得の際には、データ送信元となった SIM の IMSI を指定し、${API-KEY}, ${API-TOKEN} の部分は、ご自身の API 認証情報に置き換えてください。

  • API リクエストを送信する際には API リファレンス も利用できます。利用方法は FAQ を参照してください。
$ curl -X GET \
  -H "X-Soracom-API-Key: ${API-KEY}" \
  -H "X-Soracom-Token: ${API-TOKEN}" \
  https://api.soracom.io/v1/subscribers/${IMSI}/data | jq .

[
  {
    "time": 1479350771000,
    "contentType": "application/json",
    "content": "{\"temperature\":20}"
  },
  {
    "time": 1479358881000,
    "contentType": "application/json",
    "content": "{\"temperature\":22}"
  },
  {
    "time": 1479359991000,
    "contentType": "application/json",
    "content": "{\"temperature\":20}"
  }
]
TCP, UDP で Harvest Data にデータを送信すると、その内容が Base64 エンコードされた上で JSON に組み込まれます。

LoRa デバイスから送信されたデータ

LoRa デバイスから送信されたデータも同様に soracom-cli を使う方法と API を使う方法の二通りで取得できます。

soracom-cli では、soracom lora-devices get-data コマンドを使います。${LoRaデバイスID} の部分にはデータ送信元の LoRa デバイスの ID に置き換えてください。

$ soracom lora-devices get-data --device-id {LoRaデバイスID} --coverage-type jp

以下のように getDataFromLoraDevice API に対して GET リクエストを送信します。データ取得の際には、データ送信元の LoRa デバイス ID を指定し、${API-KEY}, ${API-TOKEN} の部分は、ご自身の API 認証情報に置き換えてください。

  • API リクエストを送信する際には API リファレンス も利用できます。利用方法は FAQ を参照してください。
$ curl -X GET \
  -H "X-Soracom-API-Key: ${API-KEY}" \
  -H "X-Soracom-Token: ${API-TOKEN}" \
  "https://api.soracom.io/v1/lora_devices/${LoRaデバイスID}/data"

ステップ 4: データを可視化する

ユーザーコンソールでは、Harvest Data で収集された JSON 形式のデータを可視化できます。

まず IoT SIM 管理画面を開いて、SORACOM Harvest Data による通信を行った IoT SIM にチェックマークを付けます。続いて、[操作] ボタンから [データを確認] を選択します。

SIM一覧

画面遷移した状態では、データがロードされていません。[検索] ボタンを押すと、Harvest Data で収集されているデータがグラフで表示されます。 Harvest Data のグラフ表示画面の特徴については Harvest Data で可視化する を参照してください。

ステップ 5: Harvest Data を無効化する

Harvest Data は有料のサービスです。Harvest Data が有効になっていると SIM 1 枚ごとにオプション料金が発生します。不要となった場合には設定を無効化してください。

  1. グループ一覧画面で、Harvest Data の設定を行ったグループをクリックし、グループ詳細画面を開きます。
  2. SORACOM Harvest Data 設定グループの中にあるスイッチを OFF に設定し、保存ボタンをクリックしてください。

以下のようにコマンドを実行し、Harvest Data を無効化します。${group_id} の部分は SIM グループの ID に置き換えてください。

$ soracom groups put-config --group-id ${group_id} --namespace SoracomHarvest --body '[{"key":"enabled","value":false}]'

API で設定を無効化するには、putConfigurationParameters API を使って Group Config の一部として設定を入れます。以下のように HTTP PUT リクエストを送信してください。${API-KEY}, ${API-TOKEN} の部分は、ご自身の API 認証情報に置き換えてください。

  • API リクエストを送信する際には API リファレンス も利用できます。利用方法は FAQ を参照してください。
$ curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Soracom-API-Key: ${API-KEY}" \
  -H "X-Soracom-Token: ${API-TOKEN}" \
  -d "[{\"key\":\"enabled\",\"value\":false}]" \
  "https://api.soracom.io/v1/groups/{group_id}/configuration/SoracomHarvest"