SORACOM Developers

SORACOM Harvest Getting Started

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

はじめに

SORACOM Harvest(以下、Harvest) とは、IoT デバイスからのデータ収集および可視化サービスです。SORACOM Air が提供するセルラー通信を使って、IoT デバイスのセンサーデータ等を手間なくクラウドにアップロードすることができます。アップロードされたデータは、SORACOMプラットフォーム上に 40 日間に渡って保存されます。お客様は、保存されたデータを SORACOM のユーザーコンソールでグラフ化することができます。

Getting Started

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

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

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

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

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

主な仕様は以下のとおりです。

項目
データの送信プロトコル HTTP, TCP, UDP
1回に送信できるデータサイズの最大値 1 KB
データ保存期間 40日間
Harvest側での暗号化機能 なし (暗号化が必要な場合はクライアント側でご対応ください)
HTTPエントリポイント (HTTP) http://harvest.soracom.io
TCP, UDPエントリポイント (TCP, UDP) harvest.soracom.io:8514

※ LoRa デバイスからデータを送信する場合、エントリポイントやプロトコルの指定は不要で、LoRa グループで Harvest を有効化するだけですぐに Harvest を使うことができます。

注意
Harvest のエントリポイントには、Air SIM 以外から接続できません。動作確認の際には Air SIM で通信を行っていることを確認してください。

Harvestを有効化する

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

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

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

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

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

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

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

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

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

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

Harvest 設定

soracom-cliでの設定方法

soracom-cliで設定する場合、soracom groups put-config コマンドでHarvestを有効化します。以下のように引数を指定し、コマンドを実行してください。${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

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を利用します。

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

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

soracom-cli を使う方法

soracom-cli では、soracom subscribers get-data コマンドを使います。Air SIM for Japanのデータを取得する場合には以下のようにコマンドを実行すると、保存されているデータを取得できます。${IMSI} の部分はデータ送信元の Air 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にデータを送信すると、その内容が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 で収集されたデータを可視化する

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

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

SIM一覧

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

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

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

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

soracom-cliでの設定方法

以下のようにコマンドを実行し、Harvest を無効化します。${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 Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

サービス機能詳細

Developer Tools

pagetop