デバイスのデータを 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 にデータが保存されます。
Harvest Data に保存されたデータを確認するには
Harvest Data に保存されたデータを確認する操作については、SORACOM 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!'
バイナリデータを送信する例:
$ echo "0102030405060708" | xxd -r -p | curl -v -X POST http://harvest.soracom.io \
-H "content-type: application/octet-stream" \
--data-binary @-
HTTP でデータを送信する場合、Harvest Data のエントリポイントに HTTP POST リクエストを送信します。
import requests
header = {}
payload = {"temperature": 20}
response = requests.post("http://harvest.soracom.io", headers=header, json=payload)
print(response.status_code)
print(response.text)
上記のコードの header = {} を header = {"x-soracom-timestamp": f'1671883114123'} に変更して、x-soracom-timestamp ヘッダーに任意の時刻の UNIX 時間 (ミリ秒) (1671883114123 の場合は 2022 年 12 月 24 日 20:58:34.123) を指定すると、データの送信日時を変更できます。
Harvest Data のエントリポイント (harvest.soracom.io:8514) に TCP でデータを送信します。なお、TCP で送信した場合は、Harvest Data ではバイナリデータとして処理され、payload 変換が行われます。
簡単にテストする場合は、telnet コマンドが便利です。
データを送信する例:
$ 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 コマンドが便利です。なお、UDP で送信した場合は、Harvest Data ではバイナリデータとして処理され、payload 変換が行われます。
テキストを送信する例:
$ echo -n "hello" | nc -u -w10 harvest.soracom.io 8514
201
送信が成功すると、上記のようにレスポンスコード 201 が返ります。
バイナリデータを送信する例:
$ echo "00060102030405064917" | xxd -r -p | nc -u -w10 harvest.soracom.io 8514
201
送信が成功すると、上記のようにレスポンスコード 201 が返ります。
正しく保存できるデータについて
- マルチバイト文字を送信する際は、ユーザーコンソールでの文字化けを避けるために、UTF-8 でエンコードしてください。
- 正しく保存できる整数値の上限は、9007199254740991 (2 の 53 乗 - 1) です。この値を超える整数値は正しく保存できない場合があります。
Lagoon 3 で UNIX 時間のデータを可視化する場合は
リクエストボディ (JSON) で UNIX 時間を送信して、Lagoon 3 で時刻のデータとして可視化する際は、以下の点に注意してください。
- UNIX 時間 (ミリ秒) を送信します。
- Lagoon 3 で、[Standard options] の を設定します。
リソース ID とデータの保存日時 (ミリ秒) が一致した場合の処理について
データは、リソース ID (*1) ごとに、データの保存日時 (ミリ秒) をキーとして保存されます。そのため同一のリソース ID から、既存のデータと同一のタイムスタンプを指定してデータを送信した場合、先に送信したデータは以下のルールで上書きされます。
(*1) たとえば、IoT SIM を利用した場合は SIM ID のこと。
データ形式が JSON の場合は、プロパティごとに上書きされます。つまり、すでに保存されているプロパティは、同一プロパティで上書きされないかぎり維持されます。
データ形式が JSON 以外の場合は、古いデータは削除され、新しいデータに上書きされます。
バイナリデータとして処理されると payload 変換が行われます
Harvest Data に送信されたデータが バイナリデータ として処理される場合は、payload 変換が行われたうえで保存されます。payload 変換について詳しくは、payload 変換について を参照してください。
LoRaWAN デバイスや Sigfox デバイス、Inventory デバイスでも Harvest Data にデータを保存できます
詳しくは、以下のページを参照してください。
任意の時刻のデータとして Harvest Data に保存する
以下のいずれかの方法で、任意の時刻のデータとして Harvest Data に保存できます。なお、リソース ID とデータの保存日時が一致した場合、先に送ったデータが上書きされます。詳しくは、リソース ID とデータの保存日時 (ミリ秒) が一致した場合の処理について を参照してください。
x-soracom-timestampヘッダーで UNIX 時間 (ミリ秒) を指定すると、任意の時刻のデータとして Harvest Data に保存できます。日本時間の 2022 年 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 }'を有効化すると、「送信データに含めた時刻」のデータとして Harvest Data に保存できます。詳しくは、送信したデータに含めた時刻をタイムスタンプに利用する を参照してください。
日本時間の 2022 年 12 月 24 日 20 時 58 分 34 秒 123 (
1671883114123) に送信したデータとして保存する例:$ curl -v -X POST http://harvest.soracom.io \ -H "content-type: application/json" \ -d '{ "temperature": 21, "time": 1671883114123 }'
有効範囲外の日時を指定した場合はデータは保存されません
「上記の方法で指定した時刻」が「Harvest Data がデータを処理する時刻」と比較して「40 日 (3456000 秒) 以上過去」または「1 日 (86400 秒) 以上未来」のときは、Harvest Data へのデータの保存に失敗します。データ送信時にエラーレスポンスを受け取った場合は、対象のデータを更新したうえで再送してください。