IoT機器で使うデータ通信SIMについて、IMSI（SIMカードに記録された加入者識別番号）とシリアル番号（SIMカード表面に刻印）の対応表および、その状態管理が必要になった。
これはSIMを契約する Soracom Console の画面から確認できるものの、CSVなどで一括ダウンロードする機能は無かったので、SORACOMが提供するAPIでSIMの一覧を取得した。

Qiitaに似たような記事が見つからなかったので手順を残す。

２通りの認証方法

SORACOM APIを呼び出すには、APIキーとトークンが必要。

APIキーとトークンは、

ルートアカウントによる認証
SAMユーザによる認証

の何れかで取得できる。

SAMユーザの認証キーを準備

ルートアカウントによる認証でAPIキーとトークンを取得する場合、本項は必要ないので読み飛ばして構わない。

SAM（SORACOM Access Managament）とは、管理するユーザごとにアクセス権限を設定できる機能で、AWSにおけるIAMと同じ概念だ。

SAMユーザの作成

コンソール右上のボタンから「セキュリティ」をクリック

「ユーザー作成」をクリック

任意のユーザ名で作成

認証キーペアの生成

「認証キー生成」をクリック

認証キーのペアをメモ

生成された認証キーIDと認証キーシークレットを使って auth API を呼び出すと、SAMユーザとして SORACOM API を利用できる。

APIキーとトークンの取得

curlでAPIを叩き、得られるJSONデータをjqで整形する。

jqは標準で入っていないため、リポジトリからインストールする。

CentOSの場合

sudo yum -y install epel-release
sudo yum -y install jq

Ubuntuの場合

sudo apt -y install jq

auth API の実行

ルートアカウントによる認証の場合

SORACOMユーザコンソールにログインするときのメールアドレスとパスワードを指定する。

コマンド

curl -X POST -H 'Content-Type: application/json' \
    -d '{ "email": "メールアドレス", "password": "パスワード" }' \
    https://api.soracom.io/v1/auth | jq -r '.apiKey, .token' > auth.txt

SAMユーザによる認証の場合

SAMユーザの認証キーペアを指定する。

コマンド

curl -X POST -H 'Content-Type: application/json' \
    -d '{ "authKeyId": "keyId-XXXXXX", "authKey": "secret-XXXXXX" }' \
    https://api.soracom.io/v1/auth | jq -r '.apiKey, .token' > auth.txt

トークンを環境変数に記憶

1行目にAPIキー、2行目にトークンが入るので、環境変数に export して以後、使いまわす。
ただし、デフォルトで24時間を経過するとトークンは無効になるので、その場合は取り直すこと。

コマンド

export API_KEY=`head -1 auth.txt`
export TOKEN=`tail -1 auth.txt`
rm auth.txt

トークンを永続記憶域に保存するのは好ましくないため、export後に削除している。

listSubscribers API の実行

SIMの一覧を取得するAPIを呼び出す。
SORACOM APIでは、一部の例外を除いて、APIキーとトークンをヘッダーに含めることになる。

コマンド

curl -X GET -H "X-Soracom-API-Key: $API_KEY" -H "X-Soracom-Token: $TOKEN" \
    https://api.soracom.io/v1/subscribers | jq -r '.[]|[.imsi, .serialNumber, .tags.name]|@csv'

出力例（IDは架空のもの）

"440203798982612","DN0604301362160","開発用"
"440104997074918","DN0504305931512","PoC"
"440105299076502","DN0504406531350","横浜02"
"440112195316932","DN0304306818711","神戸15"
"440202899419837","DN0504206814950","広島29"

SIMは「Subscriber（加入者）をIdentity（識別）するためのModule」の略と考えると、SIMの一覧を取得するAPIが Subscribers なのは理解できると思う。

さいごに

SORACOM API の一覧は https://dev.soracom.io/jp/docs/api に掲載されている。
通信量の詳細を取得するAPIもあるので、例えば下図のようなIoTレポートをPython等で生成することも容易になる。