Soracom

Users

ドキュメント
Home ドキュメント SORACOM Air for セルラー そのほかの機能

デバイスで IoT SIM の情報を利用する (メタデータサービス)

SORACOM Air メタデータサービス機能 (以下、メタデータサービス) を利用すると、デバイスで動作するアプリケーションが、デバイスで利用する IoT SIM の情報を簡単に取得したり更新したりできます。

メタデータサービスを使わない場合は、IoT SIM の情報を取得したり更新したりするには、SORACOM API を利用する必要があります。そして SORACOM API を利用するためには、セキュリティを考慮しつつ、デバイスがアクセスできる場所に認証情報を保存する必要があります。

一方、メタデータサービスを使うと、メタデータサービスの URL にアクセスするだけで IoT SIM の情報を取得したり更新したりできます。認証情報は必要ありません。

IoT SIM を利用するデバイスでメタデータサービスの URL にアクセスします

メタデータサービスは、IoT SIM を利用するデバイスでメタデータサービスの URL にアクセスすることで、追加の認証情報を省略できる仕組みです。URL にアクセスする時点で、すでに IoT SIM レベルでの認証ができているため、追加の認証情報は不要です。

メタデータサービスのユースケース

デバイスごとに異なる設定情報をデバイスの外部に保存し、デバイスの起動時などをトリガーに、設定情報をデバイスの外部 (SORACOM プラットフォーム) から取得してデバイスに適用するアーキテクチャで利用されることを想定しています。

このアーキテクチャを使うことで、デバイスを量産するときの個体差を無くすことができるため、初期設定手順の削減が期待できます。さらに、設定情報を SORACOM プラットフォームから取得するため、デバイスの出荷後に設定を変更できて便利です。詳しくは、デバイスや環境に依存する設定情報を SORACOM から取得する を参照してください。

そのほか、以下のようなユースケースでも利用できます。

デバイスのアプリケーションから IoT SIM 固有の情報にアクセスする

スマホアプリなど、デバイスのアプリケーションから IoT SIM の IMSI や設定されたタグを参照 したり、IoT SIM の速度クラスを変更 したりできます。

デバイスのファームウェア管理

メタデータサービスの ユーザーデータ を利用して、デバイスのファームウェアを遠隔管理できます。たとえば、以下のような動作をするアプリケーションをデバイスに用意することで実現できるユースケースです。

  1. デバイスの最新ファームウェアのバージョン番号やダウンロード URL といったメタデータを、JSON 形式でユーザーデータに設定します。
  2. アプリケーションがユーザーデータを定期的に取得し、ファームウェアが更新されていないか確認します。
  3. ファームウェアが更新されていた場合は、アプリケーションがメタデータサービスを通じて IoT SIM の速度クラスを変更し、ファームウェアをダウンロードします。
  4. ダウンロードが完了したら、アプリケーションが IoT SIM の速度クラスを元に戻します。
  5. アプリケーションがファームウェアを更新します。

デバイスのブートストラッピング

IoT SIM に設定されたタグごとに異なる設定で、デバイスのアプリケーションを初期化できます。たとえば、以下のような動作をするアプリケーションをデバイスに用意することで実現できるユースケースです。

  1. デバイス共通で使用できる初期化スクリプトを用意します。

    必要に応じて、メタデータサービスの ユーザーデータ に、初期化スクリプトを設定して、ダウンロードして実行することもできます。詳しくは、メタデータサービスを利用してユーザーデータにアクセスする を参照してください。

  2. 初期化スクリプトでは IoT SIM に設定された タグ を元に、デバイスを初期化します。

メタデータサービスを設定する

メタデータサービスを有効化し、ユーザーデータなどを設定します。

メタデータサービスの設定はグループに対して行います

ここでは、グループの設定を変更する操作のみを説明します。グループの仕組みやグループを作成する操作について詳しくは、グループ設定 を参照してください。

  1. SIM グループ画面で [SORACOM Air for セルラー設定] をクリックします。

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

  2. [メタデータサービス] をクリックして「ON」にします。

    メタデータサービス設定 メタデータサービス設定

  3. 設定を変更します。

    項目説明
    [読み取り専用]チェックが入っている場合は、メタデータの書き込み (POST / PUT。メタデータサービスの URL を利用して IoT SIM の情報を更新すること) ができません。
    [レスポンスボディを最小化]チェックが入っている場合は、メタデータの書き込み (POST / PUT) に成功したときのレスポンスボディが空になります。なお、失敗したときは、この設定にかかわらずレスポンスボディにエラーメッセージが返されます。
    [許可するオリジン]Cross-Origin Resource Sharing (CORS) のオリジンをひとつ設定できます。Ajax 等でメタデータサービスの URL にアクセスするために必要です。
    [ユーザーデータ]メタデータサービスを利用して取得する任意のデータ (テキスト形式または JSON 形式) を入力できます。データ形式に合わせて [JSON 形式で保存] を設定してください。なお、ユーザーデータの取得方法について詳しくは、メタデータサービスを利用してユーザーデータにアクセスする を参照してください。
    [JSON 形式で保存][ユーザーデータ] のコンテンツタイプを指定します。テキスト形式 (Content-Type: text/plain) のデータを入力した場合は、チェックを外します。JSON 形式 (Content-Type: application/json) のデータを入力した場合は、チェックを入れます。
  4. [保存] をクリックします。

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

    IoT SIM のメタデータサービスが有効化されます。

ユーザーデータのコンテンツタイプは text/plain または application/json のいずれかです。それ以外のコンテンツタイプは使用できません。

ユーザーデータに入力できるデータの制限

ユーザーデータに限った上限値は、設定されていません。ただし、グループ設定 全体の JSON のサイズの上限は 8 KiB です。

デフォルトではメタデータを書き込めません

メタデータを書き込めない設定の場合は、以下のエラーメッセージが返されます。

  • You are not allowed to execute POST request.
  • You are not allowed to execute PUT request.

メタデータを書き込めるようにするには、[読み取り専用] のチェックを外してください。

SORACOM CLI / SORACOM API の場合

SORACOM CLI または SORACOM API を利用しても、メタデータサービスの設定を変更できます。

  • SORACOM CLI を利用するには、あらかじめ SORACOM CLI をインストールし、認証情報を保存してください。詳しくは、SORACOM CLI をインストールする を参照してください。
  • {group_id} は、soracom groups list (Group:listGroups API) で取得できます。
  • {namespace} は、SoracomAir です。
  • ボディで指定するプロパティについては、ボディで指定するプロパティについて を参照してください。
  • ここでは、グループの設定を変更する操作のみを説明します。グループの仕組みやグループを作成する操作について詳しくは、グループ設定 を参照してください。

メタデータサービスを設定する

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

$ soracom groups put-config --group-id {group_id} --namespace SoracomAir \
--body '[
  {
    "key": "metadata",
    "value": {
      "enabled": true,
      "readonly": true,
      "minimizeResponseBody": true,
      "allowOrigin": "http://some.example.com"
    }
  },
  {
    "key": "userdata",
    "value": "foobar"
  }
]'

メタデータサービスを設定する

Group:putConfigurationParameters API を使用します。

$ curl -v -X PUT https://api.soracom.io/v1/groups/{group_id}/configuration/SoracomAir \
-H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
-H "X-Soracom-Token: $X_SORACOM_TOKEN" \
-H "Content-Type: application/json" \
-d '[
  {
    "key": "metadata",
    "value": {
      "enabled": true,
      "readonly": true,
      "minimizeResponseBody": true,
      "allowOrigin": "http://some.example.com"
    }
  },
  {
    "key": "userdata",
    "value": "foobar"
  }
]'

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

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

keyvalue の型value
metadataObject

以下のプロパティを含む JSON オブジェクトを設定します。

プロパティ説明
enabledBoolean

メタデータサービスの ON/OFF を設定します。

  • true: ON。メタデータサービスを利用できます。
  • false: OFF
readonlyBoolean

読み取り専用の ON/OFF を設定します。

  • true: ON。メタデータサービスの URL を利用して、IoT SIM の情報を更新できません。
  • false: OFF
minimizeResponseBodyBoolean

レスポンスボディの最小化の ON/OFF を設定します。

  • true: ON。メタデータの書き込み (POST / PUT) に成功したときのレスポンスボディが空になります。なお、失敗したときは、この設定にかかわらずレスポンスボディにエラーメッセージが返されます。
  • false: OFF
allowOriginStringCross-Origin Resource Sharing (CORS) のオリジンをひとつ設定できます。Ajax 等でアクセスを行うために必要です。
userdataString または Object

ユーザーデータを設定します。

  • String を設定した場合は、ユーザーデータのコンテンツタイプは text/plain になります。
  • Object を設定した場合は、ユーザーデータのコンテンツタイプは application/json になります。

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

メタデータサービスを利用して IoT SIM の情報にアクセスする

IoT SIM の情報にアクセスするには、IoT SIM を利用するデバイスで、以下の URL (デバイスが利用する IoT SIM の情報を取得、更新する URL) にアクセスします。

http://metadata.soracom.io/v1/subscriber

これで、認証情報が必要な Subscriber:getSubscriber API を呼び出したときと同じ情報を取得できます。

メタデータサービスでアクセスできる SORACOM API

SORACOM プラットフォームで https://api.soracom.io/v1/subscribers/{imsi} 配下の API リクエストが、http://metadata.soracom.io/v1/subscriber (メタデータサービス) にマッピングされています。つまり、Subscriber:* API に掲載されている /subscribers/{imsi} 配下のすべての API に、メタデータサービスからアクセスできます。

例:

項目SORACOM API を利用してアクセスする場合メタデータサービスを利用してアクセスする場合
GET の例GET https://api.soracom.io/v1/subscribers/{imsi}GET http://metadata.soracom.io/v1/subscriber
POST の例POST https://api.soracom.io/v1/subscribers/{imsi}/update_speed_classPOST http://metadata.soracom.io/v1/subscriber/update_speed_class
PUT の例PUT https://api.soracom.io/v1/subscribers/{imsi}/tagsPUT http://metadata.soracom.io/v1/subscriber/tags
DELETE の例DELETE https://api.soracom.io/v1/subscribers/{imsi}/tags/{tag_name}DELETE http://metadata.soracom.io/v1/subscriber/tags/{tag_name}

メタデータの読み取り例: IoT SIM の情報を取得する

メタデータの読み込み例として、IoT SIM の情報を取得する方法を紹介します。メタデータサービスを有効化した IoT SIM を利用するデバイスから、以下のコマンドを実行してください。

$ curl -s http://metadata.soracom.io/v1/subscriber
{
  "imsi": "44010xxxxxxxxxx",
  "msisdn": "81xxxxxxxxxx",
  "ipAddress": "10.xxx.xxx.xxx",
  "apn": "soracom.io",
  "type": "s1.fast",
  "groupId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": 1437119287341,
  "lastModifiedAt": 1448436038512,
  "expiredAt": null,
  "terminationEnabled": false,
  "status": "active",
  "tags": {
    "name": "xxxx"
  },
  "sessionStatus": {
    "lastUpdatedAt": 1448419048209,
    "imei": "xxxxxxxxxxxxxxx",
    "location": null,
    "ueIpAddress": "10.yyy.yyy.yyy",
    "dnsServers": [
      "100.127.0.53",
      "100.127.1.53"
    ],
    "online": true
  },
  "speedClass": "s1.fast",
  "moduleType": "nano",
  "plan": 1,
  "expiryTime": null,
  "operatorId": "OPxxxxxxxxxx",
  "createdTime": 1437119287341,
  "lastModifiedTime": 1448436038512
}
import requests
import json

response = requests.get("http://metadata.soracom.io/v1/subscriber")

if response.status_code == requests.codes.ok:
  print(json.dumps(response.json(), indent=2))
else:
  print("Status: ", response.status_code)
  print("Response: ", response.text)

IoT SIM の IMSI (imsi)、名前 (tags.name)、ステータス (status)、速度クラス (speedClass) など、IoT SIM の情報を JSON 形式で取得できます。そのほかの情報については、Subscriber:getSubscriber API を参照してください。

IoT SIM で接続していることを確認するには

IoT SIM の情報を使って、デバイスが IoT SIM で接続していることを確認できます。 具体的には、subscriptionsessionStatus.online の値を確認します。

まず、以下のコマンドを実行します。

$ curl -s http://metadata.soracom.io/v1/subscriber.subscription
plan01s

ここで planArc01 が表示されたときは、IoT SIM で接続していません。Arc で接続されています。planArc01 以外が表示されたときは、IoT SIM で接続している可能性があります。次のコマンドを実行してください。

$ curl -s http://metadata.soracom.io/v1/subscriber.sessionStatus.online
true

ここで、true が表示されたときは、IoT SIM で接続しています。なお、初めのコマンドで planArc01 が表示されたときは、2 回目のコマンドで true が表示されても、Arc で接続されています。

なお、以下のエラーメッセージが表示された場合は、メタデータサービスが「ON」になっていません。詳しくは、メタデータサービスを設定する を参照してください。

Subscriber is not configured to route request to /v1/subscriber

メタデータの読み取り例: クエリ機能を使用する

メタデータサービスのクエリ機能は、メタデータサービスの URL の末尾に .{API レスポンスに含まれる JSON の Key} という文字列を追加してアクセスすることで、Key に紐づく値のみが取得できる仕組みです。必要な部分だけ取得できるため、通信量を削減できます。

たとえば、メタデータから IMSI だけ取得するには、以下のようにリクエストします。

$ curl -s http://metadata.soracom.io/v1/subscriber.imsi
44010xxxxxxxxxx
import requests

response = requests.get("http://metadata.soracom.io/v1/subscriber.imsi")
print(response.text) # Expect to output IMSI of using SIM (15 digits)
クエリ機能は読み込み専用の機能です

クエリ機能はメタデータの書き込みには対応していません。

メタデータの読み取り例: HTTP クライアントを使わずにクエリ機能でメタデータを取得する

HTTP クライアントを使用しなくても、TCP コネクションが作成できればメタデータを取得できます。JSON のパースが難しいデバイスでも、メタデータを利用できます。

telnet コマンドで IMSI を取得するには、以下のコマンドを実行します。

$ telnet metadata.soracom.io 80
Trying 100.127.100.127...
Connected to metadata.soracom.io.
Escape character is '^]'.
GET /v1/subscriber.imsi

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Thu, 15 Dec 2016 08:19:57 GMT
Connection: close

440101234567890
Connection closed by foreign host.

デバイスで動作するアプリケーションで利用する際は、レスポンスの中で 2 回連続で出力された改行を目印にすれば、メタデータの値だけを取得できます。

メタデータの書き込み例: 速度クラスを変更する

メタデータサービスを利用して、速度クラス を変更できます。

$ curl -s -X POST http://metadata.soracom.io/v1/subscriber/update_speed_class \
-H "Content-Type:application/json" \
-d '{
  "speedClass": "s1.standard"
}'
{
  "imsi": "4401xxxxxxxxxxx",
      :
  "type": "s1.standard",
      :
  "speedClass": "s1.standard",
      :
}
import requests
import json

payload = {'speedClass': 's1.standard'}
response = requests.post("http://metadata.soracom.io/v1/subscriber/update_speed_class", json=payload)

if response.status_code == requests.codes.ok:
  print(json.dumps(response.json(), indent=2))
else:
  print("Status: ", response.status_code)
  print("Response: ", response.text)

速度クラスが変更されていることを確認します。

$ curl -s http://metadata.soracom.io/v1/subscriber.speedClass
s1.standard
import requests

response = requests.get("http://metadata.soracom.io/v1/subscriber.speedClass")
print(response.text)
レスポンスボディが空になる場合があります

[レスポンスボディを最小化] にチェックが入っている場合は、メタデータの書き込みに成功したときのレスポンスボディが空になります。

なお、失敗したときは、以下のようにレスポンスボディにエラーメッセージが返されます。

{
  "code": "SEM0039",
  "message": "Invalid speed class s1.non-existent-class specified"
}

メタデータの書き込み例: IoT SIM のタグを追加 / 更新する

IoT SIM のタグ を追加したり更新したりします。

$ curl -s -X PUT http://metadata.soracom.io/v1/subscriber/tags \
-H "Content-Type:application/json" \
-d '[
  {
    "tagName": "sample",
    "tagValue": "sample-value"
  }
]'
{
  "imsi": "4401xxxxxxxxxxx",
      :
  "tags": {
    "sample": "sample-value"
  },
      :
}
import requests
import json

payload = [{'tagName': 'sample', 'tagValue': 'sample-value'}]
response = requests.put("http://metadata.soracom.io/v1/subscriber/tags", json=payload)

if response.status_code == requests.codes.ok:
  print(json.dumps(response.json(), indent=2))
else:
  print("Status: ", response.status_code)
  print("Response: ", response.text)

タグが更新されていることを確認します。

$ curl -s http://metadata.soracom.io/v1/subscriber.tags
{
  "sample": "sample-value"
}
import requests
import json

response = requests.get("http://metadata.soracom.io/v1/subscriber.tags")

if response.status_code == requests.codes.ok:
  print(json.dumps(response.json(), indent=2))
else:
  print("Status: ", response.status_code)
  print("Response: ", response.text)
レスポンスボディが空になる場合があります

[レスポンスボディを最小化] にチェックが入っている場合は、メタデータの書き込みに成功したときのレスポンスボディが空になります。

なお、失敗したときは、以下のようにレスポンスボディにエラーメッセージが返されます。

{
  "code": "SEM0121",
  "message": "The length of tag name (300 bytes) exceeds the limit. The max length after URL encoding is 256 bytes."
}

メタデータの削除例: IoT SIM のタグを削除する

IoT SIM のタグ を削除します。

$ curl -s -X DELETE http://metadata.soracom.io/v1/subscriber/tags/sample
import requests
import urllib

tag_name = urllib.parse.quote("sample")
response = requests.delete("http://metadata.soracom.io/v1/subscriber/tags/" + tag_name)
print(response.status_code) # Expect return 204

タグが更新されていることを確認します。

$ curl -s http://metadata.soracom.io/v1/subscriber.tags
import requests
import json

response = requests.get("http://metadata.soracom.io/v1/subscriber.tags")

if response.status_code == requests.codes.ok:
  print(json.dumps(response.json(), indent=2))
else:
  print("Status: ", response.status_code)
  print("Response: ", response.text)
  • タグ名は、UTF-8 で URL エンコード (パーセントエンコーディング) してください。JavaScript の場合は、encodeURIComponent() を利用します。なお、タグの名前に半角スペースを含む場合は、半角スペースを %20 に置き換えてください。+ に置き換えると削除できません。

    例:

    • ABC DEFABC%20DEF
    • ABC DEF%EF%BC%A1%EF%BC%A2%EF%BC%A3%20%EF%BC%A4%EF%BC%A5%EF%BC%A6
  • 失敗したときは、以下のようにエラーメッセージが返されます。

    {
      "code": "SEM0001",
      "message": "No such resource found"
    }
    

メタデータサービスを利用してユーザーデータにアクセスする

メタデータサービスの [ユーザーデータ] に設定した、テキスト形式または JSON 形式のデータを取得できます。メタデータサービスのユーザーデータにアクセスするには、IoT SIM を利用するデバイスで、以下の URL (ユーザーデータを取得する URL) にアクセスします。

$ curl -s http://metadata.soracom.io/v1/userdata
import requests
import json

response = requests.get("http://metadata.soracom.io/v1/userdata")
print(response.text)

ここでは [ユーザーデータ] の活用例として、ユーザーデータにシェルスクリプトを設定した場合を紹介します。ユーザーデータの設定方法については、メタデータサービスを設定する を参照してください。

#!/bin/bash
echo THIS IS USERDATA.
echo My name is $(curl -s http://metadata.soracom.io/v1/subscriber.tags.name)
  1. ユーザーデータを設定したグループに所属する IoT SIM を利用するデバイスから、以下のコマンドを実行します。

    $ curl -s http://metadata.soracom.io/v1/userdata
    
    #!/bin/bash
    echo THIS IS USERDATA.
    echo My name is $(curl -s http://metadata.soracom.io/v1/subscriber.tags.name)
    
  2. ユーザーデータを設定したグループに所属する IoT SIM を利用するデバイスから、以下のコマンドを実行します。

    取得したユーザーデータがコマンドとして実行され、IoT SIM の名前が取得されます。

    $ curl -s http://metadata.soracom.io/v1/userdata | bash
    
    THIS IS USERDATA.
    My name is (IoT SIM 名)
    
メタデータサービスを利用してユーザーデータを書き込むことはできません

IoT SIM の情報とは異なり、IoT SIM を利用するデバイスでも、認証なしでユーザーデータを書き込むことはできません。これは、ユーザーデータの更新には Group:* API を使用するためです。デバイスからユーザーデータを更新するには、SORACOM CLI / SORACOM API を使用してください。