SORACOM Developers

Getting Started

SORACOM Air メタデータサービス機能を使用する

このドキュメントでは、SORACOM Air のメタデータサービスを利用する方法を紹介します。 メタデータサービスでは、デバイス自身が使用している Air SIM の情報を HTTP 経由で取得、更新することができます。

はじめに 〜メタデータサービスとは〜

Amazon Web Service(AWS) の EC2 や Google の GCE といったクラウド上の仮想マシンサービスにはメタデータサービスと呼ばれる機能があります。この機能では、インスタンスに固有のデータ(インスタンスのIDやネットワークの情報など)を HTTP で取得する事ができます。

SORACOM Air のメタデータサービスは、Air SIM を使用するデバイス自身から、Air SIM の情報を HTTP 経由で取得することができます。また、書き込みアクセスが許可されている場合には、速度の変更、タグの追加など、各種操作が行えます。
デバイス単体で API コールをする場合にも、SDK を使用する必要なく、非常に単純なコードで API コールが行えます。また、デバイスにクレデンシャルを持たせる必要がなくなり、セキュリティ強化にも役立ちます。

メタデータに対する読み込み・書き込みリクエストは、内部的には https://api.soracom.io/v1/subscribers/{SIMのIMSI} 配下のAPIリクエストにマッピングされる仕組みとなっています。API リファレンスに掲載されている subscribers/{imsi} 配下のものであれば全てのAPIを実行可能です。

メタデータサービスを有効にする

SORACOM のユーザーコンソールで、対象の Air SIM が所属しているグループの詳細画面を開きます。

注意
メタデータサービスを利用するには、SIMをグループに登録する必要があります。事前にグループを作成し、 SIM をグループに登録してください。

設定項目一覧の中から「SORACOM Air 設定」をクリックすると、メタデータサービスの設定画面となります。

メタデータサービス設定

各項目の意味は、以下の通りとなります。

メタデータサービスにアクセスする

メタデータサービスの URL (デバイス自身が使用している Air SIM の情報を取得、更新する URL)は、以下となります。SORACOM Air を使用しているデバイスで、以下の URL にアクセスすると、

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

以下の API にアクセスしたものと同様の結果が返ってきます。

https://api.soracom.io/v1/subscribers/{SIMのIMSI}

メタデータに対する読み込み・書き込みリクエストは、内部的には https://api.soracom.io/v1/subscribers/{SIMのIMSI} 配下のAPIリクエストにマッピングされる仕組みとなっています。API リファレンスに掲載されている subscribers/{imsi} 配下のものであれば全てのAPIを実行可能です。

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

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

$ curl -s http://metadata.soracom.io/v1/subscriber | jq .
{
  "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": "moto"
  },
  "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
}

​ Air SIM の ISMI、名前、タグ、速度クラスなど、Air SIM の情報がJSON形式で表示されました。

API 呼び出しで同様の情報を取得しようとすると、先に認証APIを呼び出しトークンを付与してからSubscriberの情報を取得するAPIを呼び出す必要があります。一方で、メタデータサービスの場合、トークンは付与していません。既に SIM レベルでの認証が出来ているので、ここでは単純に HTTP でアクセスするだけでよい、という事になります。

メタデータの読み取り:クエリ機能

先のセクションではAPIで取得できる情報すべてを読み込む例を紹介しましたが、メタデータのクエリ機能を使うと、メタデータの中で必要な部分だけ読み出すこともできます。

この機能では、メタデータのURLの後ろに .{APIレスポンスに含まれるJSONのKey} と文字列を付けてメタデータにアクセスすることで、APIの戻り値となるJSONのKeyに紐づくValueが返る仕組みになっています。

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

$ curl -s http://metadata.soracom.io/v1/subscriber.imsi
440101234567890
注意
クエリ機能はメタデータの書き込みには対応していません。読み込みに限り利用できます。

クエリ機能の特徴:HTTPクライアントを使わずにメタデータを取得する

クエリ機能では、HTTPクライアントを使わなくとも、TCPコネクションが作成できればメタデータを取得することができます。JSONのパースが難しいようなデバイスであっても、メタデータを使うことができるのがクエリ機能の特徴です。

HTTPクライアントを使わないでメタデータを取得する場合のコマンド例は以下のとおりです。telnetコマンドででメタデータサーバの80/tcpポートにTCPコネクションを作成し、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 -sX POST -d '{"speedClass":"s1.standard"}' -H 'Content-Type:application/json' \
http://metadata.soracom.io/v1/subscriber/update_speed_class | jq .speedClass
"s1.standard"
$ curl -s http://metadata.soracom.io/v1/subscriber | jq .speedClass
"s1.standard"

速度クラスの変更が、単なる HTTP POST で実行出来ています。 通常、API コールをする場合には SDK を使用することになりますが、この機能を使えば非常に単純なコードで API コールが行えます。 また、デバイスにクレデンシャル情報を持たせる必要がなくなります。

ユーザデータにアクセスする

​ メタデータサービスの設定項目にある「ユーザデータ」には、ユーザーが独自のデータを設定できます。例えばスクリプトを入れておくなどの用途が考えられます。 ユーザデータには、以下の URL からアクセスすることができます。

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

ここでは、以下のようにユーザデータを設定します。 ​ メタデータサービス設定

#!/bin/bash
echo THIS IS USERDATA.
echo My name is $(curl -s http://metadata.soracom.io/v1/subscriber | jq -r .tags.name )

設定したグループに含まれる Air 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 | jq -r .tags.name )
$ curl -s http://metadata.soracom.io/v1/userdata | bash
THIS IS USERDATA.
My name is (Air SIM 名)

​ ユーザデータで指定したコマンドを実行し、Air SIM の名前を取得することができました。

注意
ユーザデータはメタデータとは異なり、Air SIM経由で通信しているデバイスであっても認証なしでデータを書き込み (POST) することはできません。これは、ユーザデータの更新には Group API を呼ぶ必要があることに由来しています。
デバイスからユーザデータの更新を行う場合には、他のSORACOM APIを実行するときと同様に、API Key / API Token を使って認証を行い、putConfigurationParameters API を呼び出してください。

ユースケース

​ メタデータサービスを使用することで、例えば以下のようなユースケースが考えられます。 ​

スマホアプリから SIM 固有の情報にアクセスする

メタデータサービスを通じて、Subscriber に設定されたタグを参照したり、自身の回線スピードを変更したり出来ます。 ​

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

ファームウェア情報をユーザデータとして保存しておき、メタデータサーバを通じてデバイスが取得し、更新があった場合にメタデータサービスを通じてスピードクラスを変更し、ダウンロードが完了したらスピードクラスを元に戻す、といった処理が簡単に実装できます。 ​

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

共通で使用できる初期化スクリプトをユーザデータに設置しておき、スクリプト中で Subscriber に設定されたタグの情報を元にソフトウェアを構成する、といった事が可能です。 ​

現在の仕様

URL

現在のメタデータサービスは、以下の URL からアクセスできます。

ユーザデータに保存できるデータサイズの上限値

ユーザデータに限った上限値は現時点では設定されておらず、グループ設定(Group Configuration)全体で8KBが上限値です。

SORACOM の各種サービス機能は、Group に基づいて設定の管理が行われ、その設定情報は「グループ設定」と呼ばれます。メタデータやユーザデータは、Air, Beamなどの各種サービスの設定情報とともに1つのグループ設定として取り扱われ、全体で上限8KBまでの設定情報を登録することができます。

Getting Started

SORACOM Air for セルラー

SORACOM Air for LoRaWAN

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

サービス機能詳細

Developer Tools

pagetop