Soracom

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

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

一方、メタデータサービスを使うと、メタデータサービスの 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 のメタデータサービスが有効化されます。

SORACOM CLI / SORACOM API の場合

SORACOM CLI または SORACOM 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"
  }
]'

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

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

以下の key と value のペアを配列で指定します。

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

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

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

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

メタデータの読み取り例: 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 を参照してください。

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

plan01s

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

true

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.

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

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

$ 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)

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

メタデータサービスの [ユーザーデータ] に設定した、テキスト形式または 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 名)