API を利用した自動化: SIM の発注から管理を自動化する | SORACOM API 利用ガイド

SORACOM API を活用して IoT SIM の発注から設定を自動化する方法を紹介します。API の実行にあたっては Sandbox 環境を利用することで、本物の IoT SIM を発注することなく無料で検証できます。以下を事前に参照してください。

シナリオ

SORACOM Air for セルラーの IoT SIM は 1 枚単位で SORACOM IoT ストアやユーザーコンソールで発注できます。数枚単位であればブラウザから逐次発注し、届いた 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 環境のセットアップ

本物の IoT SIM を発注することなく無料で検証するため、Sandbox 環境をセットアップします。SORACOM API Sandbox 利用ガイドの「1. 本番環境で SAM ユーザーを準備する」「2-B. SORACOM CLI を用いたオペレーターの準備」を参照してください。

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

準備が完了したら、Sandbox 環境で SORACOM CLI を実行していきます。

Sandbox 環境での架空の IoT 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) ナノサイズ (データ通信のみ)」を示しています。商品コードの一覧は以下のコマンドで確認できます。SORACOM API を使用する場合は、Order:listProducts API を使用します。

実行例

$ 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

発注した IoT SIM を登録する

出荷された IoT SIM を登録することで、IoT SIM に対する操作やデータ通信ができます。API を用いる場合は registerOrderedSim をお使いください。getOrder で orderStatus パラメータが変更されていることを確認できます。なお、実際の環境では納品書に発注 ID が記載されています。商品の納品後に当手順を実施してください。

実行例

$ soracom --profile sandbox orders register-subscribers --order-id ${ORDER_ID}
$ soracom --profile sandbox orders get --order-id ${ORDER_ID} | jq -r .orderStatus
received

API による IoT SIM の操作

登録した IoT SIM の一覧を確認する

API を利用して登録した IoT SIM の情報を確認できます。API を用いる場合は listOrderedSubscribers をお使いください。

実行例

$ soracom --profile sandbox orders list-subscribers --order-id ${ORDER_ID}
{
        "orderedSubscriberList": [
                {
                        "iccid": "4836513986486774402",
                        "imsi": "001012794891563",
                        "msisdn": "999386537417",
                        "serialNumber": "TS7566283633414"
                }
        ]
}

登録した IoT SIM のグループを設定する

IoT SIM の IMSI がわかれば、各種操作が IMSI を引数にして実行できます。当手順では新規にグループを作成して IoT 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

登録した IoT 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 Air for セルラーは、利用したデータ通信量に応じて課金されます。そのため、データ通信量を監視しておくことが重要です。

イベントハンドラーで、設定した上限に達した際にメールを送るといった設定をしておきましょう。イベントハンドラーも SORACOM CLI / SORACOM API で作成で設定できます。

IoT SIM の盗難リスクへの対処

SORACOM では設定したデバイス以外での通信を拒否する IMEI ロック機能を利用できます。はじめて通信を開始したデバイスに対して IMEI ロックを設定するアクションが提供されています。
IMEI ロックを設定した IoT SIM が、未登録の IMEI を持つデバイスで接続を試みて通信エラーになったときに実行されるアクションも提供されています。詳しくは、サブスクライバー / IoT SIM が IMEI ロックにより接続失敗したら実行を参照してください。

Soracom

Users

SIM の発注から管理を自動化する

シナリオ

準備

API を実行する PC の用意

jq のインストール

SORACOM CLI のインストール

Sandbox 環境のセットアップ

Sandbox 環境での架空の IoT SIM 発注と受け取り、登録

配送先の住所を登録する

実行例

商品を選択する

実行例

実行例

発注を確定する

実行例

Sandbox 上で商品を出荷する

実行例

発注した IoT SIM を登録する

実行例

API による IoT SIM の操作

登録した IoT SIM の一覧を確認する

実行例

登録した IoT SIM のグループを設定する

実行例

登録した IoT SIM にタグをつける

実行例

さらなる応用

IoT SIM の盗難リスクへの対処