投稿日

【Ask SA!】SORACOM Harvest Dataを使いこなすデータフォーマットとAPIの活用方法

こんにちは。ソリューションアーキテクトの小梁川/koyaです。ソラコムのソリューションアーキテクトおよびプロフェッショナルサービスコンサルタントがSORACOMを活用する技術情報をお届けするAsk SAシリーズの投稿です。

本投稿ではSORACOM Harvest Dataをデータ中心にみてお話してみようと思います。本投稿での目的はデータを使う(貯める、可視化する)ためにという点に特化してHarvest Dataを整理してみようと考えています。全般的な機能ガイドや設定方法などは適宜リンクと関連情報のまとめリンク情報を最後に書いておきますのでそちらをご参照ください。

はじめに

IoTのプロジェクトで簡単にPoCを始めてみたい、IoT対応製品を初めて作ってみるが初期フェーズからバックエンドサーバを構築したくない、楽をしたい。といったケースで通信にSORACOMをご選択いただける場合には、SORACOM Harvest Data/Lagoonのご利用をおすすめしています。
SORACOM Harvest Dataはデータストアの機能とSORACOMコンソールからデータを確認できる機能を提供しております。また、SORACOM Lagoonはダッシュボード機能を提供しており、データの可視化やしきい値監視による警報を行うことができます。また単純にデータストアとしてご利用いただき、APIもしくはGUIからデータをダウンロードしてExcelなどの使い慣れたツールにいれて集計するなどの利用方法も可能になるかと思います。

簡易なテストやPoCを行う上でこれらのサービスをご利用いただくメリットとしては、

  • インフラを構築する事なくSORACOMコンソールからの設定だけで利用可能
  • 契約するサービスをSORACOMに集約する

といったあたりがあります。

もちろん、既存のインフラがある場合は、必ずしもこれらのサービスをご利用いただく必要はございません。

SORACOM Harvest Dataの利用ユースケース例

これはあくまでも一例ですが、

  • センサーデータのストア、可視化（パネル化やダッシュボードが必要な場合は、Lagoonを併用）
  • 単純なデータストアとして利用し、API/GUIからデータを取得しExcelや自社サービスへのインポート
  • 機械学習などの教師データ、データストアとしてご利用いただき、機械学習ベンダーがAPIでHarvestからデータを取得
  • デバイスやゲートウェイを開発しているお客様が簡単にデータストアを提供することで製品付加価値をあげる

などがあります。

データの取り扱い

SORACOM Harvest Dataをご利用いただく場合、SORACOMサービスがデータをどのように取り扱うのかや、データフォーマットをどうすればよいのかという点を最初に理解いただくことが重要になります。例として、今回は私の手元の環境で、Thing(Raspberry Pi＋USBドングルでSORACOM Airを利用) -> Hevest Data -> Lagoonでどのようにデータを取り扱われるのかをデータ視点とインターフェース視点で整理してみます。

HarvestへJSON形式でデータを送る場合

デバイスが送るデータ構造

Thingとして、私のRaspberry Piが送るデータを以下のJSON型としてデータをUDPで Harvest へ向けて送ってみます。

*UDPでデータを送信する場合、JSON形式のデータをbase64でエンコードされたbyteデータへ変換して送信しています。

{
 "device": "test_device",
 "time" : unixtime,
 "value1" : int, #乱数
 "value2" : string #数字を文字列としておくる
 "value3" : string #適当な文字列 「OK/NG]
}

Havest Dataに格納されているデータ

下記のHarvest Dataの画面を見ていただくとわかると思いますが、‘データ’の列が受信したデータになりbyte型のデータであることがわかります。HavestのGUIではbyte型からデコードを行い、それを ‘一次処理済みデータ’ の列として表示しています。さらにグラフ化可能なデータを抜き出し、‘グラフ用データ’の列を表示しています。

後述しますが、ここで重要なのは、データは送信されたままのものが保管されており、GUIでは皆様が使いやすい形にデコードなどをしている点です。またグラフとしては数字データが利用可能です。このGUIでみているグラフはSORACOMコンソールでのみ利用が可能です。これで要件を達成できるのであればLagoonは必要ではありません。

Lagoonでグラフを作成する場合のデータの取り扱い

SORACOM LagoonはGrafanaをベースにしております。データソースとしてはSORACOM Harvestのみが対象となります、その他ご自身で作成されたGrafana環境との差分はこちらをご参照ください。Lagoonではさまざまなグラフや表をパネル表示可能ですが、
ここでは先程送信したJSONデータをテーブルとして表示してみます。以下のようにJSONのフィールドに合わせて列が作成されています。ここでのtimeはデータがHarvest Dataへ到着した時間を用いております。こちらのtimeも後ほど、APIでデータを取得してみるで説明します。
ここではtableにデータを表示しているだけですが、当然グラフなどのパネルを設置することもできます。パネル作成方法なども最後にリンクを付けておきます。
各項目で設定できることなどはこちらをご参照ください
ダッシュボードの機能概要はこちらをご参照ください

Harvest DataへCSV形式でデータを送る場合

デバイスがおくるCSVデータ

先程のデータを単純にCSV形式にして送ってみます。
以下の形式でデータを送信してみます。

test_device_csv, unixtime, int, string, [OK/NG]

Harvest Dataに格納されているデータ

データストアとしてデータを受信、格納することはできていますが、JSON構造のデータではなく(フィールド情報もないので)、一次処理済みデータの表示では、valueとしてデコードされた値が格納されているだけになっています。属性が文字列の集合として一つの値となっておりグラフ用データとしては無効なものになっております。

LagoonでのCSVデータの見え方

Lagoonでtable表示してみますが、Harvest Dataと同様にデータとして表示することはできてますが、値の分類分けはできていません。

Harvest DataがもつAPIインターフェース

SORACOM Harvest Dataについて、以下のご質問をいただくことがあります。

  • データの取り出しはできるのか
  • SORACOM Air以外からのデータ投入やデータのエンリッチ/編集をしたい
  • データを削除したい

いずれも可能です。SORACOM AirからのHarvest Dataへのアクセス以外にREST APIも定義されておりますので、REST APIをご利用いただくことでSORACOM Air以外からのデータ操作が可能となります。
SORACOM Harvest Dataへのアクセスを図示すると以下のようになります。

Harvest DataのAPI定義

ソラコムのサービス網外からのHarvest DataへのアクセスはREST APIは ‘DataEntry’に属しています。
使用できるパラメータやAPIの詳細についてはAPIリファレンスのDataEntryを確認ください。

データ取得のAPI例

GET /data/{resource_type}/{resource_id}

リソースタイプとリソースIDが必須パラメータとなり、SIMをご利用のお客様の場合IMSI（SIMに割り当てられている固有識別番号）を指定することになります。ここからわかることは皆様の視点ではデバイス単位でデータを選択したいと思われることがあると思いますが、Harvest Dataの主キーとしてはSIMが中心になる点でギャップがあるかもしれません。

1つのIoT-Gatewayがあり、その下にThingやセンサーがぶら下がっている場合でもSORACOM Harvestとしては暗黙的にIMSI/SIMを主キーとして扱います。
1-Thing/1-SIMであればIMSIのみでデータを管理できますが、Gatewayに複数のThingがある場合などはデータにdevice識別できるような情報を入れる必要があり、SIMベースでデータを取得した後に必要に応じてフィルタするなどの処理が必要になるかもしれません。

APIでデータ取得

実際にAPIを実行してみましょう。＊API Key / API Tokenは認証APIを実行することで取得できますが今回は説明を省略します、認証については後述の参考からご確認ください。
ここでは認証を実行し、API Key / API Tokenを取得しているものとしています。

curl -X GET --header 'Accept: application/json' --header 'X-Soracom-API-Key:{API-KEY}' --header 'X-Soracom-Token: {TOKEN}' 'https://api.soracom.io/v1/data/Subscribers/{imei}?sort=desc'

responseは以下となりました。送信データは content、payloadにあります。time属性はharvestが追加したデータ受信時刻です。

[
 {
  "content": "{\"payload\":\"dGVzdF9kZXZpY2VfY3N2LDE1OTA2NDkyMzMsMjMsMDYxLE9L\"}",
  "contentType": "application/json",
  "time": 1590649233646
 },
 {
  "content": "{\"payload\":\"dGVzdF9kZXZpY2VfY3N2LDE1OTA2NDkyMjgsNTIsMDYwLE5H\"}",
  "contentType": "application/json",
  "time": 1590649228442
 },
 {
  "content": "{\"payload\":\"dGVzdF9kZXZpY2VfY3N2LDE1OTA2NDkyMjMsMjksMDU5LE5H\"}",
  "contentType": "application/json",
  "time": 1590649223241
 },
 <省略>
]

payloadのbyteデータ部分をdecodeしてみます。
#私はpythonが好きなので、あえてpythonでdecodeします。

$ python
import base64
print(base64.b64decode(b'dGVzdF9kZXZpY2VfY3N2LDE1OTA2NDkyMzMsMjMsMDYxLE9L'.decode()))

b'test_device_csv,1590649233,23,061,OK'

Linux shellであれば

$ echo -n "dGVzdF9kZXZpY2VfY3N2LDE1OTA2NDkyMzMsMjMsMDYxLE9L" | base64 -d

test_device_csv,1590649233,23,061,OK

検証で送っていたCSV型のデータが表示されました。

注意点

Harvest Dataからのデータ抜き出しのためにAPIを短時間で大量に発行いただくとAPIの利用上限にあたる場合がありますので、API発行の間にsleepを入れるなどをご検討ください。また、レスポンスにToo many requestsが返った場合などは十分にAPI発行間隔をとり、また、API発行間隔を調整の上で再度実行ください。関連情報にあるexponential backoffなどの考え型を取り入れていただけるとよいかと思います。高速なAPIアクセスが必要な場合はこちらよりご相談ください。

まとめ

本投稿としては、なるべくものを作らないで、PoC環境を構築する、や、デバイス検証のために必要となりそうな点に絞ってSORACOM Harvest Dataを中心にご説明しました。データの到達を確認するだけであればいずれのデータ形式でもよくLagoonでtableで表示させればHarvest到達の時刻とデータを見ることができます。一方で、数字データをグラフ化するや、属性ごとできれいに参照したい場合は JSONフォーマットでのデータを送信いただくことを推奨します。
JSONデータの作成に関して、デバイスのパワーや電源に不安のあるお客様はバイナリパーサーをご利用いただくことで解決できるケースもございます。
ここまで本投稿ではHarvest Dataでのデータの取扱について説明してきました。PoCや検証などの最初のステップでの簡易なデータストアがほしい場合や簡易な可視化であれば皆様のお手を煩わせることなく、また、確認の為に複数の業者との契約、経費処理もなく行えるのはニーズがあるのではないかなと思います。よければぜひ使ってみてください。

サービス個別の設定方法などの関連情報

（サンプル3）Harvestのデータの参照のみ許可するパーミッション構文をご参照下さい。

エンジニアブログ