みなさん、こんにちは。
SORACOM Harvest Files にファイル名の前方一致検索機能(API)を追加しましたのでお知らせします！
当機能は2020年9月時点ではAPI/CLIとして提供しています。
SORACOM Harvest Filesとは
SORACOM Harvest とは、IoT デバイスからのデータを収集、可視化およびファイルを保存するサービスです。SORACOM Air が提供するセルラー通信、LPWAでの通信を使って、IoT デバイスのセンサーデータ等を手間なくクラウドにアップロードできるサービスです。そして、Harvestは2つの機能があり、一つはテキスト、JSON、バイナリなどデータを扱うSORACOM Harvest Data(Harvest Data)、もう一つは画像やログなどのファイルを扱うSORACOM Harvest Files(Harvest Files)です。
詳細はSORACOM Harvest ユーザーガイドをご確認ください。
今回のアップデート
今回 Harvest Files にファイル名の前方一致検索機能(API)を追加しました。
当APIは、指定された検索文字列とHarvestFilesのファイルパスを前方一致でマッチしたファイルエントリの一覧を返します。
Harvest Files は、SORACOM IoT SIM からセルラー通信を使って送信されたファイルのデフォルト保存先を指定することができます。
例えばdefaultPathに /logs を設定した場合、SIMからのファイル送信時にパスの指定がない場合は /logs としてファイルが保存されます。
さらに、デフォルト保存先の設定では、プレースホルダーという便利な機能を使用できます。タイムスタンプやIMSIを指定するとソラコムがファイルパスやファイル名に置き換えて保存します。
指定できるプレースホルダーは以下のとおりです。
:time– ファイル送信時のtimestamp(unixtime):imsi– ファイル送信時に使用したIMSI
たとえば、プレースホルダーとして、デフォルト保存先に以下のように指定して、
/logs/:imsi/:time
デバイスからは以下のように、ファイルパスを指定することなく HarvestFiles に送信すると、
curl -X PUT --data-binary @a.txt -H 'content-type:text/plain' http://harvest-files.soracom.io
ファイルは以下のように保存されます！
/logs/4401xxxxxxxxz/1561780299935
IoTシステムでは大量のデバイスを扱うことが多くあります。それぞれのデバイスでファイル送信先の設定をもつことはその後の運用を考えるととても大変です。
このデフォルト保存先とプレースホルダーを使用することで、デバイス側はすべて同じ設定(送信先)でよく、クラウド側で送信先を設定(変更も)できます。
そして、今回のファイル検索機能を組み合わせると、対象のデバイス(IMSI)からアップロードされたファイルのみを取得ということができるようになります！
(/logsと指定すれば、IMSIを横断的に検索することも可能です。)
APIは以下のとおりです。
- GET /files
また、クエリパラメータで以下を指定できます。
scope: リクエストのスコープとなります。privateもしくはpublicを指定してください。prefix: ファイルパスにマッチさせるプレフィックス(前方一致の検索文字列)となります。limit: 返却するファイルエントリ数の上限last_evaluated_key: 最後に取得されたページの最後のファイルエントリのfilePath。このパラメータを指定することで次のファイルエントリ以降のリストを取得できます。
サンプルコマンドは以下のとおりです。
このサンプルコマンドではファイルパスに %2Flogs を前方一致で含むファイルを取得します。(URL エンコードされているので /logs を %2Flogs としています。CLIの場合は/logs としてしていただくとCLIが自動的にエンコーディングします。)
curl -i -H 'Content-Type: application/json' -H "X-SORACOM-API-KEY: ${SORACOM_API_KEY}" -H "X-SORACOM-TOKEN: ${SORACOM_API_TOKEN}" "https://api.soracom.io/v1/files?scope=private&prefix=%2Flogs"
[
{
"operatorId": "OP0059150966",
"filename": "harvest01.csv",
"createdTime": 1571643185445,
"lastModifiedTime": 1571643185962,
"expiryTime": 1634801585962,
"etag": "0a8f5ee00edd5468ef0ea909f4020596",
"contentType": "application/octet-stream",
"contentLength": 16,
"filePath": "/logs/harvest01.csv",
"isDirectory": false
}
]
(実際は未整形のJSONが返却されます。)
APIの使用方法はAPI利用ガイドにございますので、ご覧ください。
ぜひご利用ください！
ソラコム 江木(nori)