SORACOM Developers

SORACOM Harvest Getting Started

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

はじめに

SORACOM Harvest Data(Harvest Data) とは、IoT デバイスからのデータを収集し可視化するサービスです。SORACOM Air が提供するセルラー通信、LPWAでの通信を使って、IoT デバイスのセンサーデータ等を手間なくクラウドにアップロードできます。お客様は、保存されたデータを SORACOM のユーザーコンソールでグラフや地図にマッピングできます。 アップロードされたデータは、SORACOMプラットフォーム上に標準で 40 日間に渡って保存されます。(データ保持期間の延長により731日間保存されます。)

Getting Started

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

セットアップから動作確認と後片付けまで 4 つのステップに分かれています。

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

ステップ 1: デバイスのデータを Harvest Data で収集する

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

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-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 での設定方法

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

$ 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'

HTTPでデータを送信する

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でデータを送信する

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

LoRa デバイスからデータを送信する

LoRaWAN デバイス設定ガイドでLoRa デバイスからデータを送信する手順を解説しています。こちらをご覧ください。

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

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

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

データの取得方法には、soracom-cli を使う方法と API を使う方法があります。

soracom-cli を使う方法

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

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

API を使う方法

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

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

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

API を使う方法

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

$ 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"

ステップ 3: Harvest Data で収集されたデータを可視化する

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

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

SIM一覧

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

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

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

ユーザーコンソールでの設定方法

soracom-cliでの設定方法

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

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

Getting Started

SORACOM Air for セルラー

SORACOM Air for LoRaWAN

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Funk

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

SORACOM Napter

Gadgets

Device

サービス機能詳細

Developer Tools

pagetop