Soracom

Users

ドキュメント

Harvest Files を有効化する

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

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

Harvest Files の設定はグループに対して行います
ここでは、グループの設定を変更する操作のみを説明します。グループの仕組みやグループを作成する操作ついて詳しくは、グループ設定 を参照してください。
  1. SIM グループ画面で [SORACOM Harvest Files 設定] をクリックします。

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

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

  3. 必要に応じて、各項目を設定します。

    項目説明
    デフォルトパス当グループに含まれる SIM から送信されたファイルのデフォルトの保存先を指定します。プレースホルダーの適用ができます。(詳細は 後述 します。) 当設定はオプションです。
    ロール当グループに含まれる SIM からのリクエストの権限のロールを指定します。送信されるファイルの保存パスや読み込みできるパスの権限も設定できます。(詳細は 後述 します。) 当設定はオプションです。
    HARVEST DATA 連携Harvest Data 連携機能 を参照してください。
    連携対象のファイルパスHarvest Data 連携機能 を参照してください。
  4. [保存] をクリックします。

    はじめて SORACOM Harvest Files 設定を「ON」にした場合は、確認画面が表示されます。

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

    確認画面

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

    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 の設定を変更できます。

Harvest Files を有効にする 

soracom groups put-config (Group:putConfigurationParameters) を使用します。

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

Harvest Files を有効化する 

Group:putConfigurationParameters を使用します。

$ 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"
  }
]'

ボディで指定するプロパティについて 

以下の keyvalue のペアを配列で指定します。

keyvalue の型value
enabledBoolean

Harvest Files の ON/OFF を設定します。

  • true: ON。Harvest Files を利用できます。
  • false: OFF
defaultPathString送信されたファイルのデフォルトの保存先を設定します。
assumedRoleIdStringSIMからのリクエストの権限のロールを設定します。
想定していない値を指定した場合の動作は、定義されていません。SORACOM CLI / SORACOM API で設定を変更したあとで、SORACOM ユーザーコンソールで意図通りに設定されていることを確認してください。