デバイスのデータを Harvest Data に保存します。
操作を始める前に準備が必要です (クリックして確認してください)
(1) SORACOM Air for セルラーの IoT SIM、および IoT SIM を利用できるデバイスを準備する
各種デバイスでの IoT SIM の使用方法については 各種デバイスで SORACOM Air を使用する を参照してください。
(2) Harvest Data を有効化する
デバイスのデータを Harvest Data に保存する場合は、デバイスに取り付けた IoT SIM が所属するグループで Harvest Data を有効化します。詳しくは、Harvest Data を有効化する を参照してください。
準備完了IoT SIM を利用するデバイスで、Harvest Data のエントリポイントへデータを送信すると、自動的に送信元の IoT SIM の IMSI とタイムスタンプがデータに付与され、Harvest Data にデータが保存されます。
HTTP でデータを送信する場合、Harvest Data のエントリポイントに HTTP POST リクエストを送信します。また、データの種類を content-type で指定してください。
JSON を送信する例：
$ curl -v -X POST http://harvest.soracom.io \
-H "content-type:application/json" \
-d '{
"temperature": 20,
"latitude": 35.677097,
"longitude": 139.732950
}'
テキストを送信する例：
$ curl -v -X POST http://harvest.soracom.io \
-H "content-type: text/plain" \
-d 'Hello, SORACOM Harvest Data!'
x-soracom-timestamp ヘッダーで UNIX 時間 (ミリ秒) を指定すると、任意の時刻のデータとして Harvest Data に保存できます。
2023 年 12 月 24 日 20 時 58 分 34 秒 123 (1671883114123) に送信したデータとして保存する例:
$ curl -v -X POST http://harvest.soracom.io \
-H "content-type:application/json" \
-H "x-soracom-timestamp:1671883114123" \
-d '{
"temperature": 21
}'
なお、リソース ID とデータの保存日時が一致した場合、先に送ったデータが上書きされます。詳しくは、リソース ID とデータの保存日時 (ミリ秒) が一致した場合の処理について を参照してください。
HTTP でデータを送信する場合、Harvest Data のエントリポイントに HTTP POST リクエストを送信します。
import requests
# header = {"x-soracom-timestamp": f'1671883114123'} # Custom data send time {#http-python-header--x-soracom-timestamp-f1671883114123--custom-data-send-time}
header = {}
payload = {"temperature": 20}
response = requests.post("http://harvest.soracom.io", headers=header, json=payload)
print(response.status_code)
print(response.text)
上記のコードのコメントを外して、x-soracom-timestamp ヘッダーに任意の時刻の UNIX 時間 (ミリ秒) を指定すると、データの送信日時を変更できます。
Harvest Data のエントリポイント (harvest.soracom.io:8514) に TCP でデータを送信します。簡単にテストする場合は、telnet コマンドが便利です。
{"value":"hello\r\n"} を TCP で送信するコマンドの例は、以下のとおりです。
$ telnet harvest.soracom.io 8514
Trying 100.127.xxx.xxx...
Connected to harvest.soracom.io.
Escape character is '^]'.
hello
201
^]
telnet> quit
Connection closed.
送信が成功すると、上記のようにレスポンスコード 201 が返ります。
Harvest Data のエントリポイント (harvest.soracom.io:8514) に UDP でデータを送信します。簡単にテストする場合は、nc コマンドが便利です。
{"value":"hello"} を UDP で送信するコマンドの例は、以下のとおりです。
$ echo -n "hello" | nc -u -w10 harvest.soracom.io 8514
201
送信が成功すると、上記のようにレスポンスコード 201 が返ります。
マルチバイト文字を送信する際は、ユーザーコンソールでの文字化けを避けるために、UTF-8 でエンコードしてください。
Lagoon 3 で UNIX 時間のデータを可視化する場合は
リクエストボディ (JSON) で UNIX 時間を送信して、Lagoon 3 で時刻のデータとして可視化する際は、以下の点に注意してください。
- UNIX 時間 (ミリ秒) を送信します。
- Lagoon 3 で、[Standard options] の を設定します。
リソース ID とデータの保存日時 (ミリ秒) が一致した場合の処理について
データは、リソース ID (*1) ごとに、データの保存日時 (ミリ秒) をキーとして保存されます。また、データの保存日時は、x-soracom-timestamp で指定できます。そのため、同一リソース ID から既存のデータと同一のタイムスタンプを指定してデータを送った場合、先に送ったデータは以下のルールで上書きされます。
(*1) たとえば、IoT SIM を利用した場合は SIM ID のこと。
データ形式が JSON の場合は、プロパティごとに上書きされます。つまり、すでに保存されているプロパティは、同一プロパティで上書きされないかぎり維持されます。
データ形式が JSON 以外の場合は、古いデータは削除され、新しいデータに上書きされます。
x-soracom-timestamp を指定したときのデータ保存期間について
そのため、x-soracom-timestamp ヘッダーを使用して、データ保持期間を超えた過去の日付へデータを保存した場合、そのデータは削除されます。データ保持期間については SORACOM Harvest Data のデータ保持期間を延長する を参照してください。
LoRaWAN デバイスや Sigfox デバイス、Inventory デバイスでも Harvest Data にデータを保存できます
詳しくは、以下のページを参照してください。