Harvest Files を有効化する
IoT SIM に対して Harvest Files を有効にするには、グループを作成し、グループの Harvest Files 設定を有効にして、そのグループに IoT SIM を所属させます。
ここでは、グループの Harvest Files 設定を有効にする手順を説明します。
Harvest Files の設定はグループに対して行います
ここでは、グループの設定を変更する操作のみを説明します。グループの仕組みやグループを作成する操作について詳しくは、グループ設定 を参照してください。
SIM グループ画面で
をクリックします。SIM グループ画面を表示する操作について詳しくは、グループの設定を変更する を参照してください。
スイッチをクリックして「ON」にします。
必要に応じて、各項目を設定します。
項目 説明 デフォルトパス 当グループに含まれる SIM から送信されたファイルのデフォルトの保存先を指定します。プレースホルダーの適用ができます。(詳細は 後述 します。) 当設定はオプションです。 ロール 当グループに含まれる SIM からのリクエストの権限のロールを指定します。送信されるファイルの保存パスや読み込みできるパスの権限も設定できます。(詳細は 後述 します。) 当設定はオプションです。 HARVEST DATA 連携 Harvest Data 連携機能 を参照してください。 連携対象のファイルパス Harvest Data 連携機能 を参照してください。 をクリックします。
はじめて SORACOM Harvest Files 設定を「ON」にした場合は、確認画面が表示されます。
をクリックします。
IoT SIM から送信したデータが Harvest Files に保存できるようになりました。
グループ設定 defaultPath
グループ設定defaultPathでは、当グループに含まれる SIM から送信されたファイルのデフォルト保存先を指定します。
たとえばdefaultPathに /logs
を設定した場合で、SIM からのファイル送信時にパスの指定がない場合は /logs
としてファイルが保存されます。/logs/
を指定した場合、 最後の /
は無視され、/logs
としてファイルが保存されます。
defaultPathに /logs
を設定し、デバイスから以下のように送信した場合、デバイスから送信されたファイル a.txt
は /logs
として保存されます。
curl -X PUT --data-binary @a.txt -H "content-type:text/plain" http://harvest-files.soracom.io
以下のようにデバイスから送信時にパスを指定した場合、パスが優先されます。
curl -X PUT --data-binary @a.txt -H "content-type:text/plain" http://harvest-files.soracom.io/logs/2019070201
同一のファイルパスを対象にファイルを送信した場合、ファイルは上書きされます。
プレースホルダーの適用
グループ設定defaultPathではプレースホルダーとして以下を指定できます。
:time
- ファイル送信時の timestamp (unixtime):imsi
- ファイル送信時に使用した IMSI
たとえばdefaultPathに /logs/:imsi/:time
を設定した場合、:imsi
および :time/
はそれぞれ IMSI、ファイル送信時の timestamp に置き換えられ、ファイルは /logs/4401xxxxxxxxz/1561780299935
として保存されます、
グループ設定 assumedRoleId
グループ設定assumedRoleIdでは、グループに含まれる SIM からのリクエストの権限のロールを指定います。送信されるファイルの保存パスや読み込みできるパスの権限を設定できます。
このロールはコンソールの「セキュリティ」->「ロール」もしくは Role
API から設定します。
設定の例
{
"statements": [
{
"effect": "allow",
"api": "FileEntry:listFiles",
"condition": "pathVariable('path') matches 'firmware/versions/'"
},
{
"effect": "allow",
"api": "FileEntry:getFile",
"condition": "pathVariable('path') matches 'firmware/versions/.*'"
},
{
"effect": "allow",
"api": "FileEntry:putFile",
"condition": "pathVariable('path') matches 'logs/:imsi/.*'"
}
]
}
上記の例を SIM グループに適用した場合、グループ内に含まれる SIM は以下の操作ができます。
- パス
firmware/versions/
に含まれるファイル一覧の取得ができる - パスに
firmware/versions/
が含まれるファイルの取得ができる - パスに
logs/:imsi/
以下へのファイル保存ができる。(:imsi
は自身の IMSI に置き換えられます。これ以外のパスにファイルの保存はできません。)
Harvest Data 連携機能
グループ設定Path patternsでは、設定したパス以下に保存されたファイルの URL 情報を Harvest Data に自動的に連携できます。 Path patternsは正規表現で記述してください。
設定の例
Harvest Files の /lagoon
以下に格納されたファイルを自動で Harvest Data にも連携したい場合、以下のように Path patterns を /lagoon/.*
と設定します。
- Harvest Data 連携機能を使用した Harvest Data へのデータ送信については、Harvest Data 書き込みリクエスト料金は発生しません。また Harvest Data 利用オプションを有効とする必要はありません。
- Harvest Data 連携機能は「エントリポイント (セルラー)」のみに対応しています。IoT SIM からの Harvest Files へのファイル送信に対応しています。
SORACOM CLI / SORACOM API の場合
SORACOM CLI または SORACOM API を利用しても、Harvest Files の設定を変更できます。
- SORACOM CLI を利用するには、あらかじめ SORACOM CLI をインストールし、認証情報を保存してください。詳しくは、SORACOM CLI をインストールする を参照してください。
{group_id}
は、soracom groups list
(Group:listGroups API
) で取得できます。{namespace}
は、SoracomHarvestFiles
です。- ボディで指定するプロパティについては、ボディで指定するプロパティについて を参照してください。
Harvest Files を有効にする
soracom groups put-config
(Group:putConfigurationParameters API
) を使用します。
$ soracom groups put-config --group-id {group_id} --namespace SoracomHarvestFiles \
--body '[
{
"key": "enabled",
"value": true
},
{
"key": "defaultPath",
"value": "/test/"
},
{
"key": "assumedRoleId",
"value": "role01"
}
]'
- SORACOM API を利用するには、API キーと API トークンが必要です。詳しくは、API キーと API トークンの取り扱いについて を参照してください。
{group_id}
は、Group:listGroups API
で取得できます。{namespace}
は、SoracomHarvestFiles
です。- ボディで指定するプロパティについては、ボディで指定するプロパティについて を参照してください。
Harvest Files を有効化する
Group:putConfigurationParameters API
を使用します。
$ curl -v -X PUT https://api.soracom.io/v1/groups/{group_id}/configuration/SoracomHarvestFiles \
-H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
-H "X-Soracom-Token: $X_SORACOM_TOKEN" \
-H "Content-Type: application/json" \
-d '[
{
"key": "enabled",
"value": true
},
{
"key": "defaultPath",
"value": "/test/"
},
{
"key": "assumedRoleId",
"value": "role01"
}
]'
ボディで指定するプロパティについて
以下の key
と value
のペアを配列で指定します。
key | value の型 | value |
---|---|---|
enabled | Boolean | Harvest Files の ON/OFF を設定します。
|
defaultPath | String | 送信されたファイルのデフォルトの保存先を設定します。 |
assumedRoleId | String | SIMからのリクエストの権限のロールを設定します。 |
想定していない値を指定した場合の動作は、定義されていません。SORACOM CLI / SORACOM API で設定を変更したあとで、SORACOM ユーザーコンソールで意図通りに設定されていることを確認してください。