SORACOMのAPIを使ってSIMの一覧を取得してみた

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

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

# ２通りの認証方法
SORACOM APIを呼び出すには、**APIキー**と**トークン**が必要。

APIキーとトークンは、

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

の何れかで取得できる。

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

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

## SAMユーザの作成
コンソール右上のボタンから「セキュリティ」をクリック
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/236222/532cc14d-52f8-4a46-d6bb-380a2c4ebcf5.png)

「ユーザー作成」をクリック
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/236222/03bdfe03-48e3-e516-b2cf-c2b4aa321479.png)

任意のユーザ名で作成
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/236222/8ecaf92a-97a0-55a6-336f-da642d6461b9.png)

## 認証キーペアの生成
「認証キー生成」をクリック
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/236222/e4aa50a2-c4e8-add0-c808-55c8b369736b.png)

認証キーのペアをメモ
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/236222/5b42ae20-4d0c-69ae-f708-88c81a37f5a5.png)

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

# APIキーとトークンの取得
`curl`でAPIを叩き、得られるJSONデータを`jq`で整形する。

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

```sh:CentOSの場合
sudo yum -y install epel-release
sudo yum -y install jq
```

```sh:Ubuntuの場合
sudo apt -y install jq
```

## auth API の実行
### ルートアカウントによる認証の場合
SORACOMユーザコンソールにログインするときのメールアドレスとパスワードを指定する。

```sh:コマンド
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ユーザの認証キーペアを指定する。

```sh:コマンド
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時間を経過するとトークンは無効になるので、その場合は取り直すこと。

```sh:コマンド
export API_KEY=`head -1 auth.txt`
export TOKEN=`tail -1 auth.txt`
rm auth.txt
```

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

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

```sh:コマンド
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等で生成することも容易になる。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/236222/a4bcab7f-19ae-1371-1fda-5c5ddb734c8f.png)