SIM の発注から管理を自動化する
SORACOM API を活用して SIM の発注から設定を自動化する方法を紹介します。API の実行にあたっては Sandbox 環境を利用することで、本物の SIM を発注することなく無料で検証できます。以下を事前に参照してください。
シナリオ
SORACOM IoT SIM は 1 枚単位で SORACOM IoT ストアやユーザーコンソールから発注できます。数枚単位であればブラウザから逐次発注し、届いた SIM を確認して名前を変更したりグループへ所属させたりできますが、数十枚、数百枚単位で利用するフェーズになるとシステム化していく必要があります。当ドキュメントでは、SORACOM の提供する API や CLI を利用して自動化する方法を紹介します。
準備
API を実行する PC の用意
当ドキュメントでは SORACOM CLI を利用して API を呼び出します。Mac OS または Linux (Windows Subsystem for Linux でも可能) のターミナルから実行してください。Windows のコマンドプロンプトからでも SORACOM CLI は利用できますが、ダブルクォーテーション ("
) の扱いなどで注意が必要となります。
jq のインストール
jq とは、JSON 形式のデータをパースして、データを取り出したりできる便利なコマンドラインツールです。 jq のダウンロードページを参照してください。
SORACOM CLI のインストール
SORACOM API は curl コマンドや各種言語からも呼び出せますが、ここでは簡単に呼び出せる SORACOM CLI をインストールします。 SORACOM CLI 利用ガイドを参照してインストールしてください。
Sandbox 環境のセットアップ
本物の SIM を発注することなく無料で検証するため、Sandbox 環境をセットアップします。 SORACOM API Sandbox 利用ガイド の「1. 本番環境で SAM ユーザーを準備する」「2-B. SORACOM CLI を用いたオペレーターの準備」を参照してください。
準備が完了したら、Sandbox 環境で SORACOM CLI を実行していきます。
Sandbox 環境での架空の SIM 発注と受け取り、登録
配送先の住所を登録する
まずは発注先の住所を登録します。実際の環境ではこちらに入力した住所や企業名が、配送時の伝票に記載されます。実際に API を利用する際は --address-line1
に町名まで、--address-line2
に番地以降を入力します。配送先 ID は後に使うので、SHIPPING_ADDRESS_ID
変数に結果を格納します。API を用いる場合は
createShippingAddress および
getShippingAddress をお使いください。
実行例
$ SHIPPING_ADDRESS_ID=`soracom --profile sandbox shipping-addresses create --address-line1 "赤坂" --address-line2 "1-9-13" --building "三会堂ビル8F" --city "港区" --company-name soracom --full-name "Sora Sorao" --phone-number 080-1234-5678 --zip-code 107-0052 --state "東京都" | jq -r .shippingAddressId`
$ soracom --profile sandbox shipping-addresses get --shipping-address-id ${SHIPPING_ADDRESS_ID}
{
"addressLine1": "赤坂",
"addressLine2": "1-9-13",
"building": "三会堂ビル8F",
"city": "港区",
"companyName": "soracom",
"countryCode": "JP",
"fullName": "Sora Sorao",
"phoneNumber": "080-1234-5678",
"shippingAddressId": "3557cedf-6bce-4b5a-9cb0-92368bebfec4",
"shippingArea": "kanto",
"state": "東京都",
"zipCode": "107-0052"
}
商品を選択する
次に商品コード (productCode)、数量 (quantity)、および配送先 ID を用いて発注を準備します。EC サイトでカートに入れるようなイメージです。発注 ID は後に使うので、ORDER_ID
変数に結果を格納します。また毎回同じ発送先に商品を配送する場合は、当手順で作成した発注 ID を再利用してください。API を用いる場合は
createQuotation をお使いください。
実行例
$ ORDER_ID=`soracom --profile sandbox orders create --body "{\"orderItemList\":[{\"productCode\":\"4573326590013\",\"quantity\":1}],\"shippingAddressId\":\"${SHIPPING_ADDRESS_ID}\"}" | jq -r .orderId`
なお商品コード “4573326590013” は、2020 年 12 月時点で「特定地域向け IoT SIM (plan-D) ナノサイズ (データ通信のみ)」を示しています。商品コードの一覧は以下のコマンドで確認できます。API を用いる場合は listProducts をお使いください。
実行例
$ soracom --profile sandbox products list
{
"productList": [
{
"count": 1,
"currency": "JPY",
"price": 895,
"productCode": "4573326590013",
"productImageURLs": [],
"productName": "SORACOM Air SIM card plan-D size:Nano(for data) 1 SIM pack",
"productType": "sim",
"properties": {
"contractType": "no_sms",
"shippingScore": "1",
"simSize": "nano",
"simSubscription": "plan-D"
}
},
(以下略)
発注を確定する
選択した商品を発注します。その後、発注 ID について情報を取得することで発注の詳細を確認できます。API を用いる場合は confirmOrder および getOrder をお使いください。
実行例
$ soracom --profile sandbox orders confirm --order-id ${ORDER_ID}
$ soracom --profile sandbox orders get --order-id "${ORDER_ID}"
{
"currency": "JPY",
"email": "sample@example.com",
"orderDateTime": "20201204133818",
"orderId": "20201204133811_bbab760b",
"orderItemList": [
{
"product": {
"count": 1,
"currency": "JPY",
"price": 895,
"productCode": "4573326590013",
"productImageURLs": [],
"productName": "SORACOM Air SIM card plan-D size:Nano(for data) 1 SIM pack",
"productType": "sim",
"properties": {
"contractType": "no_sms",
"shippingScore": "1",
"simSize": "nano",
"simSubscription": "plan-D"
}
},
"productAmount": 895,
"quantity": 1
}
],
"orderStatus": "orderProcessing",
"shippingAddress": {
"addressLine1": "赤坂",
"addressLine2": "1-9-13",
"building": "三会堂ビル8F",
"city": "港区",
"companyName": "soracom",
"countryCode": "JP",
"fullName": "Sora Sorao",
"phoneNumber": "080-1234-5678",
"state": "東京都",
"zipCode": "107-0052"
},
"shippingAddressId": "3557cedf-6bce-4b5a-9cb0-92368bebfec4",
"shippingCost": 930,
"taxAmount": 90,
"totalAmount": 1915
}
Sandbox 上で商品を出荷する
実際の環境で発注された際は商品が出荷され、指定の配送先に届きますが、Sandbox 環境では API を呼び出すことで発注を「出荷済み (shipped)」状態に遷移できます。API を用いる場合は sandboxShipOrder をお使いください。 getOrder により orderStatus パラメータが変更されていることを確認できます。なお、実際の環境では当手順は不要です。
実行例
$ soracom --profile sandbox sandbox orders ship --order-id ${ORDER_ID}
$ soracom --profile sandbox orders get --order-id ${ORDER_ID} | jq -r .orderStatus
shipped
発注した SIM を登録する
出荷された SIM を登録することで、SIM 対する操作やデータ通信が可能になります。API を用いる場合は registerOrderedSim をお使いください。 getOrder により orderStatus パラメータが変更されていることを確認できます。なお、実際の環境では納品書に納品書が記載されています。商品の納品後に当手順を実施してください。
実行例
$ soracom --profile sandbox orders register-subscribers --order-id ${ORDER_ID}
$ soracom --profile sandbox orders get --order-id ${ORDER_ID} | jq -r .orderStatus
received
API による SIM の操作
登録した SIM の一覧を確認する
API を利用して登録した SIM の情報を確認できます。API を用いる場合は listOrderedSubscribers をお使いください。
実行例
$ soracom --profile sandbox orders list-subscribers --order-id ${ORDER_ID}
{
"orderedSubscriberList": [
{
"iccid": "4836513986486774402",
"imsi": "001012794891563",
"msisdn": "999386537417",
"serialNumber": "TS7566283633414"
}
]
}
登録した SIM のグループを設定する
SIM の IMSI がわかれば、各種操作が IMSI を引数にして実行できます。当手順では新規にグループを作成して SIM を所属させます。API を用いる場合は createGroup, getGroup, listOrderedSubscribers, setGroup, getSubscriber をお使いください。
実行例
$ GROUP_ID=`soracom --profile sandbox groups create | jq -r .groupId`
$ soracom --profile sandbox groups get --group-id ${GROUP_ID}
{
"configuration": {},
"createdAt": 1607086393553,
"createdTime": 1607086393553,
"groupId": "d362a4c9-ebb3-44b0-9bdf-2774758dc0bf",
"lastModifiedAt": 1607086393553,
"lastModifiedTime": 1607086393553,
"operatorId": "OP0053613082",
"tags": {}
}
$
$ IMSI=`soracom --profile sandbox orders list-subscribers --order-id ${ORDER_ID} | jq -r .orderedSubscriberList[].imsi`
$ soracom --profile sandbox subscribers set-group --group-id ${GROUP_ID} --imsi ${IMSI}
$
$ soracom --profile sandbox subscribers get --imsi ${IMSI} | jq -r .groupId
d362a4c9-ebb3-44b0-9bdf-2774758dc0bf
登録した SIM にタグをつける
グループ設定の他によく使う API として、タグの設定があります。当手順では発注 ID をタグに指定しています。API を用いる場合は putSubscriberTags, getSubscriber をお使いください。
実行例
$ soracom --profile sandbox subscribers put-tags --imsi ${IMSI} --body "[{\"tagName\":\"orderId\",\"tagValue\":\"${ORDER_ID}\"}]"
$ soracom --profile sandbox subscribers get --imsi ${IMSI} | jq -r .tags
{
"orderId": "20201204133811_bbab760b"
}
さらなる応用
SORACOM は利用したデータ通信量に応じて課金されます。そのため、データ通信量を監視しておくことが重要です。イベントハンドラー機能を用いて、設定した上限に達した際にメールを送るといった設定をしておきましょう。イベントハンドラーも API で設定できます。
その他の応用例として SIM の盗難リスクへの対処が挙げられます。SORACOM では設定したデバイス以外での通信を拒否する IMEI ロック機能を利用できます。はじめて通信を開始したデバイスに対して IMEI ロックをかけるイベントハンドラーが Limited Preview で提供されていますので、上記と合わせて利用を検討してください。