SORACOM Airをご利用のお客様からSIM管理向けに提供されている2種類のAPI 「Sim API」 と 「Subscriber API」 のどちらを利用した方が良いかご質問をいただくことがあります。これらのAPIはいずれもSIMを管理する機能を持ちますが、いざ活用するとなった際にどちらのAPIを利用すべきか判断に迷うこともあるかもしれません。このブログ記事ではSORACOM API の活用を検討中の方に向けて、それぞれのAPIがどのような機能を提供しているかを整理し、ユースケースごとの活用例をまとめました。今後のSIM管理の参考にしていただければと思います。
各APIの紹介
Subscriber API
まずは Subscriber API です。このAPIはSORACOM Air for セルラーの管理用APIで主にSIMの各種設定や契約状態を管理する目的で利用します。SORACOMのリリース当初から存在しており、今でも多くのお客様にご利用いただいています。
Subscriber API ではSIMの識別子に IMSI (International Mobile Subscriber Identity) を用います。
Sim API
もう一つの Sim API は Subscriber API に似た機能を提供しますが、 Subscriber API の多くの機能を持ち合わせつつ、サブスクリプションコンテナ やセキュアリンクサービス「SORACOM Arc」で用いる仮想SIMに対応しています。
後発となる Sim API は豊富な機能が特徴で、これから新規でSORACOM APIを利用してセルラー通信を管理するのであれば、様々な回線やプランを統一的に扱える Sim API の利用がおすすめです。
このAPIではSIMの識別子に SIM ID を用います。SIM ID は SORACOM 固有の考え方です。
APIの比較
では実際にSORACOM IoT SIMの「plan01s」というサブスクリプションを対象に、SIM情報を取得する例で2つのAPIがどのような挙動になっているか確認してみましょう。
Subscriber API ではURLに /subscribers に続いて IMSI を指定します。一方で Sim API では /sims と SIM ID を指定します。どちらも、普段Webアプリケーション開発をされている方にとっては直感的な仕組み(いわゆるREST API)になっているかと思います。
Subscriber API
Subscriber API では IMSI を指定して、単一のSIM情報をJSONオブジェクトとして取得できます。下記は plan01s のSIM情報からの一部抜粋ですが、IPアドレス (.ipAddress) やSIMのタグ (.tags) 等のSIM固有情報を取得できることがおわかりいただけるかと思います。
タグ自体は回線管理の情報として自由に設定できます。今回の出力の中になるタグには、なにやら plan01s+planX2 と書いてありますね、これは一体どういう意味でしょうか。。。次の Sim API の方を見てみましょう。
GET https://g.api.soracom.io/v1/subscribers/{imsi}
{
"apn": "soracom.io",
"iccid": "8942310xxxxxxxxxxxx",
"imsi": "29505xxxxxxxxx",
"ipAddress": null,
"msisdn": "xxxxxxxxxxxx",
"operatorId": "OP00xxxxxxxx",
"serialNumber": "8942310xxxxxxxxxxxx",
"simId": "8942310xxxxxxxxxxxx",
"speedClass": "s1.4xfast",
"status": "active",
"subscription": "plan01s",
"tags": {
"name": "plan01s+planX2"
},
"type": "s1.4xfast"
}
Sim API
下記は先程の plan01s の情報を Sim API で取得した例です。.profiles.8942310xxxxxxxxxxxx.subscribers 配下に plan01s と planX2 の2つの情報が含まれていることがわかります。なんとこのSIMは1つの物理的なSIMの中に複数のサブスクリプションコンテナが含まれるSIMだったわけです。
GET https://g.api.soracom.io/v1/sims/{sim_id}
{
"activeProfileId": "8942310xxxxxxxxxxxx",
"operatorId": "OP00xxxxxxxx",
"profiles": {
"8942310xxxxxxxxxxxx": {
"iccid": "8942310xxxxxxxxxxxx",
"otaSupported": true,
"primaryImsi": "29505xxxxxxxxx",
"subscribers": {
"29505xxxxxxxxx": {
"capabilities": {
"data": true,
"sms": true
},
"imsi": "29505xxxxxxxxxxxx",
"msisdn": "xxxxxxxxxxxx",
"status": "active",
"subscription": "plan01s"
},
"441200xxxxxxxxx": {
"capabilities": {
"data": true,
"sms": false
},
"imsi": “441200xxxxxxxxx",
"msisdn": "8120xxxxxxxxxxx",
"status": "active",
"subscription": "planX2"
}
}
}
},
"serialNumber": "8942310xxxxxxxxxxxx",
"simId": "8942310xxxxxxxxxxxx",
"speedClass": "s1.4xfast",
"status": "active",
"tags": {
"name": "plan01s+planX2"
}
}
各APIのレスポンスデータ構造の比較
先の例で Subscriber API と Sim API のデータ構造が異なることがわかりました。Sim API では物理的なSIMに関連付いた情報をまとめて管理できる点が大きなメリットです。Subscriber API では plan01s / planX2 のそれぞれの情報を取得し、利用者が2つの情報を関連付ける必要があります。SORACOM APIを活用したアプリケーション開発では、まずは Sim API で全ての機能を満たすことができるか検討していただいたうえで Subscriber API の利用を検討する流れが良いでしょう。
一方で Subscriber API / Sim API それぞれでしか機能が提供されていない場合があります。詳しい違いは、 API リファレンス にて見比べてください。
2つのAPIの違いをおさえたところで、いくつか具体的なユースケースとどちらのAPIを利用すべきかみていきましょう。
具体的なユースケースごとのAPI活用例
SIMの管理名(タグ)を変更する (双方に同等の機能がある例)
SIMの管理名(タグ)を変更する例を見てみましょう。この機能は両方のAPIで提供されていますのでこれからAPIを使い初めるのであれば Sim API をご利用いただくと良いでしょう。
Subscriber API での管理名(タグ)変更
PUT https://api.soracom.io/v1/subscribers/{imsi}/tags
Sim API での管理名(タグ)変更
PUT https://api.soracom.io/v1/sims/{sim_id}/tags
仮想SIM(vSIM)の操作 / パケットキャプチャの操作 (Sim API のみの機能の利用例)
SORACOM Arcの仮想SIM(vSIM)の操作や、SORACOM Peek のパケットキャプチャ機能は Sim API でのみサポートされています。これらのAPIをご利用の際は Sim API を選択ください。
※ これらの操作は Subscriber API ではエラーになります。必ず Sim API をご利用ください。
仮想SIMの作成
POST https://api.soracom.io/v1/sims
パケットキャプチャの開始
POST https://api.soracom.io/v1/sims/{sim_id}/packet_capture_sessions
SIMのバンドルプランを設定する (Subscriber API のみの機能の利用例)
日本カバレッジの一部のプランで提供されるバンドル機能は Subscriber API のみで提供されています。
※ これらの操作は Sim API ではエラーになります。必ず Subscriber API をご利用ください。
Subscriber API でのバンドル変更
PUT https://api.soracom.io/v1/subscribers/{imsi}/bundles
IMSI と SIM ID
ここまでのお話で何度か出てきた IMSI と SIM ID についてもう少し掘り下げてみたいと思います。
IMSI(International Mobile Subscriber Identity) はSIMに割り当てられている番号の一種です。番号の体系は国際的に標準化されていて世界中で衝突しないように管理されており、必ずSIMごとにユニークな固有の番号です。SIM ID は、SORACOM固有の仕組みで割り当てています。こちらも番号が衝突しないようにSORACOMが番号を割り当てています。
では何故SORACOMでは IMSI に加えて SIM ID でSIM管理する方法を提供しているのでしょうか。その鍵はサブスクリプションコンテナにあります。
サブスクリプションコンテナでは物理的なSIMの中に複数のIMSIが格納される特徴があり、利用される国によってモデムやバックエンドシステムからみてSIMの IMSI が変更されたようにみえます。運用中に IMSI が変ってしまうと管理上の問題になってしまうと考えられます。そこでSORACOMではサブスクリプションコンテナの構成変更の影響を受けないSIM固有の識別管理情報として SIM ID でのSIM管理を推奨しています。
なお多くのSIMで SIM ID は SIM の ICCID が登録されています。ICCID も IMSI 同様に国際的に標準化された番号体系で割り当てされていてICカードの固有番号を示す番号になっています。多くの場合でIoTデバイスとSIMは1対1の関係で管理するのが一般的であり IMSI で管理するよりも ICCID で管理する方が実際のユースケースに即している場合も多いのではないでしょうか。
余談ですがSIMには上記2つ以外にも MSISDN(電話番号) が含まれています。1つのSIMには用途に応じて沢山の固有番号が割り当てられていますね。
SIMの物理的な特徴も含めたAPIの選定
IoTシステムの運用では、どのSIMがどの IMSI または SIM ID かを判別して特定しなければなりません。APIの活用では物理的なSIM管理の流れも含めて、どちらのAPIを利用するかの検討材料としていただければと思います
SORACOMが提供するSIMにはいくつかの種類があり、印字されている情報が異なりますのでこちらで紹介します。
※ 2022年6月時点での仕様に準じて記載しており将来にわたって変更されないことを保証するものではありませんので予めご了承ください。
plan-D
カード背面には IMSI / MSISDN / 製造番号 が記載されています。SIMのチップ部背面には 製造番号 のみが記載されています。
では SIM ID ベースの管理ができないかというとそんなことはありません。SORACOMのWebコンソールでは IMSI から SIM ID を検索する機能がありますので plan-D でも Sim API を活用いただけます。
plan-K / plan-KM1
カード背面には 製造番号 のみが記載されています。SIMのチップ部背面も同様に 製造番号 のみが記載されています。
こちらも plan-D 同様にWebコンソールで 製造番号 から IMSI や SIM ID を検索できますのでどちらのAPIもご利用いただけます。
plan01s(カード型) / planX3(カード型) / plan-K2 (カード型)
カード背面には ICCID のみが記載されています。SIMのチップ部背面も同様に ICCID のみが記載されています。
plan01s では Sim API の機能をフル活用できること、券面に ICCID が記載されていることから Sim API の利用を推奨します。
plan01s(チップ型) / planX3(チップ型) / plan-K2(チップ型)
カード背面にはAPIのパラメータとして利用可能なSIM識別情報が記載されておりません。ご注意ください。
機能としてはカード型の plan01s と同じであるため Sim API の利用を推奨します。
まとめ
今回は Subscriber API と Sim API の機能の比較やユースケースごとの活用方法をご紹介しました。
沢山のSIMの管理が必要なケースでは SORACOM API が効率的な運用管理の良きパートナーになります。これから SORACOM の活用をお考えのみなさんや最近SIMが増えてきて運用管理にお悩みのみなさんにとってこのブログが少しでもお役にたてば嬉しく思います。
― ソラコム松本 (ysk)