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 を用いたオペレーターの準備」を参照してください。

以後の各 SORACOM CLI では --profile sandbox オプションを付けています。これによりセットアップした Sandbox 環境に対して API を実行できます。当オプションを付けないとデフォルトのプロファイルに対して API を実行することになりますので注意してください。また、Sandbox 以外の実際の環境では当オプションを使用しません。

準備が完了したら、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 で提供されていますので、上記と合わせて利用を検討してください。

IMEI ロックイベントハンドラー Limited Preview