soracomのSIMのmetadata取得とAPIを使いSIMの名前を変える

背景

soracomとは端末をインターネットに繋げるための通信用のSIMやその周辺の仕組みを提供してくれる会社です。
soracomのSIMを使うとmetadata（soracom内部でのSIMの状態）取得や変更を行う機能や、web APIを利用したSIM情報の取得や変更を行う機能を使えます。

仕事で使うSIMが数十台のときは手作業でSIMの番号を確認して管理画面から装置の型番をSIMの名前として登録していたのですが、一度に購入するSIMが50枚を超えたあたりから手作業による管理では時間がかかる上に間違いも発生して憂鬱になってきたのでmetadataの取得とAPIを利用してSIMの名前を変える方法を把握して名前設定を省力化しました。

備忘録として操作内容を記事に残します。

soracom本家の説明ページ

下記ページを参考にして今回の記事の内容を実施しました。
Metadata Service
デバイスで IoT SIM の情報を利用する (メタデータサービス)
SORACOM API リファレンス

使ったもの

• soracomのSIM
  この記事はplan-DのSIMで動作確認しました。
• soracomのSIMを使う装置
  この装置でmetadataを取得します。
• インターネットに繋がっているPC 
  このPCでAPIを利用します。
• jq
  APIで取得したjsonの解釈に利用します。
  ubuntuなら下記コマンドでインストール可能です。

  sudo apt install jq

SIMでmetadata取得

設定有効化: SIMをmetadata取得を許可したSIMグループに入れる

何も設定してないSIMではmetadataを取れないので、下記の操作で取得可能にします。

metadataの取得を許可したSIMグループを作る

SIMグループをまだ作っていない場合は、SIMグループページの追加ボタンを押して作ります。

SIMグループの設定の「SORACOM Air for セルラー設定」にあるメタデータサービスのトグルスイッチを押して有効にします。
SIMから情報の書き換えを行いたい場合は「読み取り専用」の選択を外しますが、今回はAPIを使って名前を変更するため「読み取り専用」を有効にしたままで良いです。

保存ボタンを押して変更を反映します。
重要です。
保存ボタンを押してなくて、自分は時間を取られました。

SIMをmetadata取得を許可したSIMグループに入れる

metadata取得を許可したグループにSIMを入れれば、metadata取得のための設定完了です。

SIMで動く装置でmetadata取得

SIMで確立したインターネット回線で下記のurlを開くとmetadataをjsonとして取得できます。
http://metadata.soracom.io/v1/subscriber

取得可能な詳しい内容はmetadataの説明書をご覧ください。
Metadata Service

SIMの名前はtags -> nameとして格納されています。

  "tags": {
    "name": "00000027"
  },

名前が設定されていない場合はtagsの中身が空です。

  "tags": {},

metadataで取得したsimIdをAPIで利用します。

  "simId": "8981000000000000000"

API用の権限を付与したSAMユーザー作成と認証キー発行

API用のSAMユーザー作成

APIでの権限を制御するためにSAMユーザーを作り、そのユーザーの認証キーでAPIを利用します。

SIM名の設定を行うためにSim:putSimTagsの権限を付与します。

{
  "statements": [
    {
      "api": [
        "Sim:putSimTags"
      ],
      "effect": "allow"
    }
  ]
}

SIM関係の情報閲覧のためにsoracomが用意している「SIMReadOnly」のロールを割り当てます。
「ロール指定」画面は上記の「権限設定」タブの下の方にあります。

上記の設定でAPIでSIM情報の閲覧とSIM名の変更が可能なSAMユーザーができました。

SAMユーザーの認証キーを発行

「認証設定」の「認証キー」にある「認証キーを生成」を押します。

表示された「認証キーID」と「認証キーシークレット」を使うので、どこかにコピーしておきます。
「認証キーシークレット」はこの画面を閉じると再表示されないので、この画面でコピーします。
（認証キーシークレットが分からなくなった場合は、認証キーIDを破棄して作り直します。）

APIを利用してSIMの名前を変更

これまでの手順で取得したsimId、認証キーID、認証キーシークレットを利用して、SIMの名前を変更します。

bashで実行する想定で、それぞれ変数にしておきます。

AUTH_KEY_ID=keyId-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AUTH_KEY_SECRET=secret-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SIM_ID=8981000000000000000

認証キーID、認証キーシークレットからAPIのキーとトークンを取得します。
APIのキーとトークンには有効期限があるので、APIの処理を何かに組み込む場合はAPIキーとトークンの取得も処理に入れる必要があります。

AUTH_KEY_ID=keyId-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AUTH_KEY_SECRET=secret-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

JSON_AUTH=$(curl -X POST https://api.soracom.io/v1/auth \
-H "Content-Type: application/json" \
-d "{
  \"authKeyId\": \"$AUTH_KEY_ID\",
  \"authKey\": \"$AUTH_KEY_SECRET\"
}")
echo $JSON_AUTH | jq

API_KEY=$(echo $JSON_AUTH | jq .apiKey -r)
API_TOKEN=$(echo $JSON_AUTH | jq .token -r)
echo $API_KEY
echo $API_TOKEN

上記のAPIのキーとトークンを取得は下記のページで説明されています。
SAM ユーザーの API キーと API トークンを発行する

動作確認としてSIMの情報を取得してみましょう。
APIのパス: /Sim/getSim

下記のコマンドでAPIのキーとトークンを利用してsimIdのSIMの情報を取得できます。
これで取得できるのはmetadataにも含まれている情報です。

SIM_ID=8981000000000000000
curl -X 'GET' \
  "https://api.soracom.io/v1/sims/$SIM_ID" \
  -H 'accept: application/json' \
  -H "X-Soracom-API-Key: $API_KEY" \
  -H "X-Soracom-Token: $API_TOKEN"

今度はこの記事の目的であるSIMの名前変更を行います。
名前変更は下記のパスで行えます。
APIのパス: /Sim/putSimTags

TAG_NAME="name of sim"
curl -X 'PUT' \
  "https://api.soracom.io/v1/sims/$SIM_ID/tags" \
  -H 'accept: application/json' \
  -H "X-Soracom-API-Key: $API_KEY" \
  -H "X-Soracom-Token: $API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "[
  {
    \"tagName\": \"name\",
    \"tagValue\": \"$TAG_NAME\"
  }
]"

成功するとtags -> nameが変わります。

JSON_SIM=$(curl -X 'GET' \
  "https://api.soracom.io/v1/sims/$SIM_ID" \
  -H 'accept: application/json' \
  -H "X-Soracom-API-Key: $API_KEY" \
  -H "X-Soracom-Token: $API_TOKEN")
echo $JSON_SIM | jq .tags

{
  "name": "name of sim"
}

soracomの管理画面でも名前が変わったのを確認できます。

期待通りにSIMの名前を変更できました。

おわり

soracomのSIMからの情報取得でIDを入手し、APIでそのIDのSIMの名前を変更できました。

参考

Metadata Service
デバイスで IoT SIM の情報を利用する (メタデータサービス)
SORACOM API リファレンス