Soracom

IoT SIM に対して Harvest Files を有効化するには、グループを作成し、グループの Harvest Files 設定を有効化して、そのグループに IoT SIM を所属させます。

ここでは、グループの Harvest Files 設定を有効化する手順を説明します。

1. SIM グループ画面で [SORACOM Harvest Files 設定] をクリックします。

   SIM グループ画面を表示する操作について詳しくは、グループの設定を変更する を参照してください。

2. スイッチをクリックして「on」にします。

3. 以下の項目を設定します。

   項目	説明
   [デフォルトパス]	グループに所属する IoT SIM を利用するデバイスから Harvest Files のエントリポイントに、ファイル名を省略して送信された場合のデフォルトのファイル名を指定します。たとえば、[デフォルトパス] に /logs.txt と指定すると、以下のコマンドで送信したファイルは、Harvest Files の /logs.txt に保存されます。 $ curl -v -X PUT http://harvest-files.soracom.io \ -H "content-type:text/plain" \ --data-binary @a.txt [デフォルトパス] では、以下のプレースホルダーを指定できます。 :imsi: IoT SIM の IMSI :time: ファイルを送信した UNIX 時間 (ミリ秒) たとえば、[デフォルトパス] に /logs/:imsi/:time/logs.txt を指定すると、上記のコマンドで送信したファイルは、Harvest Files の /logs/4401xxxxxxxxz/1561780299935/logs.txt に保存されます。 [デフォルトパス] の先頭に / を入力してください [デフォルトパス] の先頭に / を入力せずにファイルを送信すると、404 Not Found が返されます。 [デフォルトパス] の末尾の / は無視されます [デフォルトパス] の末尾に / を入力した場合、末尾の / は無視されます。 SORACOM API でアップロードする際は [デフォルトパス] は無視されます SORACOM API でアップロードする際は、グループ設定の [デフォルトパス] は反映されません。 [デフォルトパス] を設定していても、以下のようにファイル名を指定して送信すると、デフォルトパスは無視されます。 $ curl -v -X PUT http://harvest-files.soracom.io/logs/2019070201.txt \ -H "content-type:text/plain" \ --data-binary @a.txt
   [ロール]	グループに所属する IoT SIM を利用するデバイスから Harvest Files へのアップロードやダウンロードを制限できます。 [ロール] は、SAM の ロール を利用して実現していますが、SAM ユーザーに関係なく制限されます。一度設定したロールを編集する操作については、オペレーター管理ロールを編集する を参照してください。 設定の例: { "statements": [ { "effect": "allow", "api": "FileEntry:listFiles", "condition": "pathVariable('path') != null and 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/.*'" } ] } 上記の例の場合、グループに所属する IoT SIM は以下の操作ができます。 firmware/versions/ に含まれるファイルの一覧を取得できる (FileEntry:listFiles API) $ curl -v -X GET http://harvest-files.soracom.io/firmware/versions/ firmware/versions/ に含まれるファイルをダウンロードできる (FileEntry:getFile API) $ curl -v -O -X GET http://harvest-files.soracom.io/firmware/versions/firmware_X.Y.Z.tgz logs/:imsi/ 以下にファイルをアップロードできる (FileEntry:putFile API)。なお、:imsi は、IoT SIM の IMSI に置き換えられます。 $ curl -v -X PUT http://harvest-files.soracom.io/logs/440101234567890/1640962800000/logs.txt \ -H "content-type:text/plain" \ --data-binary @a.txt なお、[デフォルトパス] に、/logs/:imsi/:time/logs.txt を指定していた場合は、以下のコマンドで logs/:imsi/ にファイルをアップロードできます。 $ curl -v -X PUT http://harvest-files.soracom.io \ -H "content-type:text/plain" \ --data-binary @a.txt pathVariable('path') の評価について pathVariable('path') を評価するときの注意事項については、pathVariable(placeholder) の「pathVariable('path') の評価について」を参照してください。 ロールを設定するとすべての権限が deny された状態から評価されます ロールが未設定の場合は、すべての権限が allow されています。 ロールを設定すると、すべての権限が deny されたとみなされたうえで、設定した権限が反映されます。したがって、以下の設定のロールを指定すると、ここで説明するコマンドのうち、ファイルの一覧を取得するコマンドだけが許可されます。 { "statements": [ { "effect": "allow", "api": "FileEntry:listFiles" } ] } SAM デフォルト権限 の設定には影響を受けません。
   [Harvest Data 連携]	スイッチを「on」にして、[連携対象のファイルパス] にファイル名を正規表現で設定します。次に、デバイスからファイルを送信した際、ファイル名が一致したファイルの情報が以下の形式で Harvest Data に送信されます。 { "url": "/v1/files/private/lagoon/logs.txt", "contentType": "text/plain", "contentLength": 230, "eTag": "1234567890abcdef1234567890abcdef" } たとえば、[連携対象のファイルパス] に /lagoon/.* を設定すると、Harvest Files の /lagoon/ ディレクトリ以下にファイルをアップロードしたときに、そのファイルの情報が上記の形式で Harvest Data に送信されます。 部分一致したファイルが対象になります。たとえば、logs と入力した場合は、ファイル名に logs を含むファイルの情報が Harvest Data に送信されます。 先頭の / の有無は動作に影響を与えません。 末尾の / の有無は動作に影響を与えます。 logs/ と入力した場合は、logs で終わるディレクトリ (例: abc_logs/) 以下に保存されたファイルの情報が Harvest Data に送信されますが、logs で終わらないファイル (例: logs.txt) の情報は送信されません。 logs と入力した場合は、logs を含むファイルやディレクトリ以下に保存されたファイルの情報が送信されます。 Harvest Files にアップロードする方法は、以下の 3 種類があります。Harvest Data 連携機能の利用可否はアップロード方法によって異なります。 方法 Harvest Data 連携機能の利用可否 デバイスのファイルを Harvest Files にアップロードする ✓ SORACOM API で Harvest Files にアップロードする - ユーザーコンソールでファイルを Harvest Files にアップロードする - ✓: 利用できる。-: 利用できない。 Harvest Data 連携機能を使用した Harvest Data へのデータ送信については、Harvest Data 利用オプションを有効にする必要はありません。また、Harvest Data への書き込み料金 は発生しません。

4. [保存] をクリックします。

   確認画面が表示されます。

5. [OK] をクリックします。

   

6. IoT SIM が所属するグループを切り替えます。

   IoT SIM から送信したデータが Harvest Files に保存できるようになりました。

SORACOM CLI / SORACOM API の場合

SORACOM CLI または SORACOM API を利用しても、Harvest Files の設定を変更できます。

$ soracom groups put-config --group-id {group_id} --namespace SoracomHarvestFiles \
--body '[
  {
    "key": "enabled",
    "value": true
  },
  {
    "key": "defaultPath",
    "value": "/test/"
  },
  {
    "key": "assumedRoleId",
    "value": "role01"
  }
]'

$ 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 のペアを配列で指定します。