投稿日

SIM管理をさらに容易に！SIM管理APIに前回のセッション情報が追加されました

この度 SIM の情報取得に関するAPI群 listSubscribers API、getSubscriber API および listSims API、getSim API に previousSession 属性を追加したことをお知らせします。

APIとは？

異なるアプリケーション間をつなげることができる仕組みです。SORACOMでも様々な情報をAPIとして公開しており、このAPIを通じて他のアプリケーション(例えば業務システム)からSORACOM内の情報を参照したり、SORACOMに対して指示を出すことができるようになります。SORACOMのAPIは資料をオンラインで公開しています。

今回のAPIの更新は、多くのSIMを管理されているお客様やSIMのセッション情報を利用した管理を行っているお客様からのご要望から提供しています。様々なSIM管理関連の作業を容易に行えるようになります。

そもそも sessionStatus とは？

subscriber API や Sim API のこれまでのレスポンスは以下のとおりです。たとえば、特定のSIMに対して詳細情報を得ることができる getSubscriber APIを使用した場合、通常はこのようなレスポンスとなります。

{
  "operatorId": "OP0012345678",
  "imsi": "295050012345678",
  "iccid": "8942310000012345678",
  "subscription": "plan01s",
  "speedClass": "s1.standard",
  "status": "active",
  "sessionStatus": {
    "gtpcTeid": 2062167075,
    "lastUpdatedAt": 1599017317572,
    "imei": "350000012345678",
    "location": null,
    "cell": {
      "radioType": "lte",
      "mcc": 440,
      "mnc": 10,
      "tac": 4728,
      "eci": 49497861
    },
    "ueIpAddress": "10.123.45.67",
    "dnsServers": [
      "100.127.0.53",
      "100.127.1.53"
    ],
    "online": true
  }
}

sessionStatus 属性は現在のSIM状態に関する、たとえば以下のような情報を確認できます。

  • デバイスのIMEI(International Mobile Equipment Identifier:通信モジュールがもつ識別番号です)
  • デバイスが接続されている基地局のID (セルID)
  • 端末が使用しているネットワークの種類（LTEまたは3G/GSM)
  • セッションの日付時刻(タイムスタンプ)

大量のSIMやデバイスを管理する場合の課題

数枚のSIMを管理する場合は、ユーザーコンソールにアクセスして、各SIMのセッション詳細を直接確認することで対応できます。セッション詳細をみることで、SIMの大まかな場所(セルIDによる）や、デバイスが最後に接続した時間を確認することができます。

ただしIoTシステムでは多くの場合、大量のデバイスを管理します。SIMの数が増えてくると SIM を一つずつ確認するわけにはいかず、この作業を効率化、自動化したくなります。これらのSIMのセッション詳細情報を活用して、大規模なデバイスの管理に役立てることができます。例えば

  • 世界中に1万台のデバイスを配備している場合、セッション詳細情報に含まれる”mcc” (Mobile Country Code)属性を使用することで、使用されている国を確認することができます。たとえばこれを利用して、使用されている国ごとにSIMをグループ化したり、タグを付与することができます。 さらに、SIMをグループ化することで、エリアごとに段階的な更新などを行うことができます。
  • 大量のデバイスから一定の期間オフラインになっているSIMを見つけたい。lastUpdatedAt`属性を使って長い間接続されていないSIMの有無を調べ、デバイスの状態を確認することができます。

sessionStatus からこのような情報を確認し、SIMを管理するためのスクリプトを開発する際にはとても有用です。

新たに追加された previousSession 属性

これまでデバイスがオフラインの場合、sessionStatus のレスポンスは以下のとおりでした。(オフラインなのでセッション情報が取得できません。)

"sessionStatus": {
  "gtpcTeid": 0,
  "lastUpdatedAt": 1520603586157,
  "imei": null,
  "location": null,
  "ueIpAddress": null,
  "dnsServers": null,
  "online": false
},

これまでも、 listSessionEvents API か listSimSessionEvents API を使うことで、前回のセッションの詳細を確認することができました。ただし、一度に1つのSIMのみの照会となりました。1,000枚のSIMがあり、そのうちの半分がオフラインの場合、現在オフラインのSIMの前回のセッションの詳細を見つけるために500回のAPIコールを追加で行う必要がありました。

今回のアップデートで、前回のセッションの詳細が listSims と listSubscribers API に新しい previousSession 属性の下に含まれるようになりました。この属性には、SIMがオフラインであっても、常に前回のセッションの詳細が含まれます。例えば、以下のようになります。

"sessionStatus": {
  "gtpcTeid": 0,
  "lastUpdatedAt": 1520603586157,
  "imei": null,
  "location": null,
  "ueIpAddress": null,
  "dnsServers": null,
  "online": false
},
"previousSession": {
  "gtpcTeid": 2062167075,
  "imei": "350000012345678",
  "cell": {
  "radioType": "lte",
  "mcc": 440,
  "mnc": 10,
  "tac": 4728,
  "eci": 49497861
},

listSims API と listSubscribers API はすべてのSIMのリストを返すので、オフラインのSIMのセッション詳細を確認するために、別のAPIを使用する必要はありません。

previousSession 属性は常に前回のセッションの詳細を含みます。

  • SIMがオンラインの場合、previousSessionは現在のセッションの前のセッション情報を表示します。
  • SIMがオフラインの場合、previousSession は直前のセッションを表示します。

API/CLI でシンプルにパワフルに！

previousSession属性を利用して、いくつかの強力な自動化を構築することができます。
例えば、CLI (コマンドラインインターフェイス) を使用した以下のコマンドでは、お持ちのすべてのSIMを取得し、それらのICCID、IMSI、IMEIをCSV形式で出力します。

$ soracom subscribers list --fetch-all | jq -r '.[] | select(.previousSession.cell.mcc == 440) | [.iccid, .imsi, .previousSession.imei] | @csv'

例の中で使用している soracom コマンドに関してはSORACOMユーザーサイト “soracom-cli” をご覧ください。APIの呼び出しがこのコマンドで簡単に行えるようになります。

もちろん、これは簡単な例に過ぎません。
ぜひ、ソラコムのAPI/CLI、今回ご紹介した previousSession やセッション詳細情報を使用して、IoTデバイスの管理を効率化してください！

ソラコム Felix