MENU
はじめに
Getting Started
ユーザーコンソールの操作
さまざまな機能の使い方
トラブルシューティングとサポート
リファレンス

Soracom

Users

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

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

メタデータサービスの概要

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

SORACOM Air のメタデータサービスは、IoT SIM を使用するデバイス自身から、IoT SIM の情報を HTTP 経由で取得できます。書き込みアクセスが許可されている場合には、速度の変更、タグの追加など、各種操作が行えます。

デバイス単体で API コールをする場合にも、SDK を使用する必要なく、非常に単純なコードで API コールが行えます。デバイスにクレデンシャルを持たせる必要がなくなり、セキュリティ強化にも役立ちます。

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

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

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

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

メタデータサービス設定

各項目の意味は、以下の通りです。

  • メタデータサービス トグルボタン: ON にすることで、メタデータサービスが有効となります。
  • 読み取り専用 チェックボックス: デバイスからのアクセス(API 操作)を読み込みのみとするかを制御します。
  • 許可するオリジン : Cross-Origin Resource Sharing (CORS) 用のオリジン設定です。外部サイトから Ajax 等でアクセスを行う際に設定が必要です。
  • ユーザーデータ : ユーザー独自のデータを任意に定義します。使用方法は ユーザーデータにアクセスする を参照してください。

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

メタデータサービスの URL (デバイス自身が使用している IoT 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 すべてが実行可能です。

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

メタデータの読み込み例として、SIM の情報を取得する方法を紹介します。メタデータを有効化した IoT 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
}

IoT SIM の ISMI、名前、タグ、速度クラスなど、IoT SIM の情報を JSON 形式で取得できました。

API 呼び出しで同様の情報を取得する際は、まず認証 API を呼び出しトークンを取得してから SIM の情報を取得する 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 コネクションを作成し、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 リクエストで SIM カードの速度クラスが変更できます。 通常、API コールをする場合には SDK を使用することになりますが、この機能を使えば非常に単純なコードで API コールが行えます。 また、デバイスにクレデンシャル情報を持たせる必要がなくなります。

メタデータの書き込み例: タグを更新する

以下のようにメタデータサービスへの書き込みアクセスで SIM のタグ も追加・更新できます。

$ curl -sX PUT -d '[{"tagName": "sample","tagValue": "sample-value"}]' -H "Content-Type:application/json" http://metadata.soracom.io/v1/subscriber/tags | jq .tags
{
  "sample": "sample-value"
}

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

メタデータサービスの設定項目にある ユーザーデータ には、ユーザー独自のデータを設定できます。例えばスクリプトを入れておくなどの用途が考えられます。ユーザーデータには、以下の 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 )

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

ユーザーデータで指定したコマンドを実行し、IoT SIM の名前を取得できました。

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

ユースケース

メタデータサービスを使用することで、以下のようなユースケースが考えられます。​ メタデータサービスで IMSI 情報を取得し Microsoft Azure Event Hubs と接続する 例も参照してください。

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

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

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

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

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

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

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

リファレンス: 制限事項と注意事項 を確認してください。