Soracom

Users

ドキュメント
Home ドキュメント SORACOM Harvest Getting Started with SORACOM Harvest Files

SORACOM Harvest Files を有効化する

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

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

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

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

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

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

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

keyvalue の型value
enabledBoolean

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

  • true: ON。Harvest Files を利用できます。
  • false: OFF
defaultPathString送信されたファイルのデフォルトの保存先を設定します。詳しくは、[デフォルトパス] の説明を参照してください。
assumedRoleIdStringIoT SIM からのリクエストの権限のロールを設定します。詳しくは、[ロール] の説明を参照してください。

想定していない値を指定した場合の動作は、定義されていません。SORACOM CLI / SORACOM API で設定を変更したあとで、SORACOM ユーザーコンソールで意図通りに設定されていることを確認してください。