Soracom

Users

ドキュメント

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

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

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

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

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

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

デバイスのデータを Harvest Data に保存する場合は、デバイスに取り付けた IoT SIM が所属するグループで Harvest Data を有効化します。詳しくは、Harvest Data を有効化する を参照してください。

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

HTTP でデータを送信する場合、Harvest Data のエントリポイントに 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

Harvest Data のエントリポイント (TCP もしくは UDP) (harvest.soracom.io:8514) にデータを送信します。簡単にテストする場合は、telnet コマンドが便利です。

hello を TCP で送信するコマンドの例は、以下のとおりです。

$ 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 が返ります。

Harvest Data のエントリポイント (TCP もしくは UDP) (harvest.soracom.io:8514) にデータを送信します。簡単にテストする場合は、nc コマンドが便利です。

hello を UDP で送信するコマンドの例は、以下のとおりです。

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

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

LoRaWAN デバイスを設定するステップ 2: SORACOM Harvest Data を使って疎通確認する に手順を解説しています。

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

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

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

データを確認したりダウンロードしたりできます。

  1. ユーザーコンソール にログインし、データを送信した IoT SIM にあわせてカバレッジタイプを変更します。

    たとえば、plan01s の IoT SIM でデータを送信した場合は、グローバルカバレッジの表示に変更します。詳しくは、SORACOM ユーザーコンソールで表示するカバレッジタイプを変更する を参照してください。

  2. [メニュー][SIM 管理] の順にクリックします。

    SIM 管理画面が表示されます。

  3. データを送信した IoT SIM にチェックを入れ、[操作][データの確認] の順にクリックします。

    送信されたデータが表示されます。

    なお、JSON 形式でダウンロードすることもできます。詳しくは、Harvest Data に格納されたデータをダウンロード (バックアップ) する を参照してください。

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 形式でエンコードされた上で payload プロパティに設定された JSON で保存されます。

たとえば、123hello を送信した場合は、SORACOM CLI や SORACOM API では以下のように表示されます。

[
  { // "123" を送信した場合
    "content": "{\"payload\":\"MTIz\"}",
    "contentType": "application/json",
    "time": 1638440726831
  },
  { // "hello" を送信した場合
    "content": "{\"payload\":\"aGVsbG8=\"}",
    "contentType": "application/json",
    "time": 1638440674779
  }
]

また、SORACOM ユーザーコンソールでは自動的にデコードされるため、以下のように表示されます。

送信したデータ (文字列)データ一次処理済みデータグラフ用データ
hello{"payload":"aGVsbG8="}{"value":"hello"}{}
123{"payload":"MTIz"}{"value":"123"}{"value":123}

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

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

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

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

以下のように getDataFromLoraDevice API に対して GET リクエストを送信します。データ取得の際には、データ送信元の LoRaWAN デバイス 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一覧 SIM一覧

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

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

Harvest Data は有料のサービスです。Harvest Data が有効になっていると SIM 1 枚ごとにオプション料金が発生します。オプション料金の発生を抑えるには、デバイスに取り付けた IoT SIM が所属するグループで Harvest Data を無効化します。詳しくは、Harvest Data を無効化する を参照してください。