SORACOM, INC.

User Console »
Documents

SORACOM API Sandbox 利用ガイド

ここでは SORACOM API Sandbox をご利用いただくために必要な情報をご提供いたします。

概要

SORACOM API Sandbox(以降、Sandbox)とは、SORACOM API の利用方法を学習したり、API を試してみたりすることができる環境です。Sandbox で実行された API は実際の Air SIM には影響しませんので、API を呼び出すことが難しいような処理(解約など)を試してみることができます。

SORACOM API 利用ガイド にも一度事前に目を通しておいてください。

なお、Sandbox の利用にあたっては、本番環境のアカウントを所有されている必要があります。

注意事項

Sandbox をお使いいただく上で、いくつか注意事項があります。

  1. Sandbox は、一部本番環境とは異なる動作をする場合があります。 例えば、イベントハンドラーを設定することはできますが、そのイベントハンドラーは現状では条件が整っても起動されません。

  2. Sandbox に保存された情報は、永続化を保証しません。SORACOM 側の都合でデータベースをクリーンアップしたりすることがあります。 したがいまして、SORACOM API Sandbox を使って CI(Continuous Integration: 継続的インテグレーション)などを行う場合は、毎回オペレーターの作成(サインアップ)から環境を構築してテスト等を行うようにしてください。そのための Sandbox 専用 API を用意しておりますのでご利用ください。

  3. Sandbox はベストエフォートで提供されるサービスです。バージョンアップなどのため予告なくメンテナンスを実施することがあります。 Sandbox に関するお問い合わせは、通常通りサポートより受け付けております。ただし、本番環境に関するお問い合わせ対応を優先させていただくものとします。

SORACOM API Sandbox を利用する

ここからは、Sandbox 環境を利用するための手順を説明します。 以下のような流れになります。

  1. 本番環境で SAM ユーザーを準備する(一度だけ)
  2. Sandbox 環境でオペレータを作成する
  3. Sandbox 環境で架空の SIM を作成し登録する

1. 本番環境で SAM ユーザーを準備する

Sandbox 環境では、本番環境とユーザーアカウント(オペレーター)や SIM(サブスクライバー)の情報などを共有しません。

ただし、本番環境にアカウントを持っていることを確認させていただく必要があるので、予め本番環境において SAM ユーザーを作成し、認証キーを生成しておいてください。

この SAM ユーザーに対しては権限の付与は必要ありません。またこの SAM ユーザーで本番環境のコンソールにログインできるようにする必要もありません。 誤った操作を防止するため、何の権限も持たずコンソールにもログインできない、Sandbox 認証専用 SAM ユーザーを作成されることを推奨いたします。

SAM ユーザーの作成方法や認証キーの生成方法につきましては SORACOM Access Managementを使用して操作権限を管理する を参照してください。

なお、Sandbox 環境を利用するための準備としての本番環境側での SAM ユーザーの作成を行う必要があるのは、最初の一度だけです。一度 SAM ユーザーと認証キーを作成したら、以降はそれを繰り返し利用することができます。

2. Sandbox 環境でオペレーターを作成する

本番環境で SAM ユーザーを作成し認証キーを生成したら、Sandbox 環境での作業に移ります。

ここからの作業は、Sandbox 環境を利用するときは毎回行う必要のある準備です。

2-1. Sandbox 環境にオペレーターを作成する

まず Sandbox 専用のオペレーターを作成していただく必要があります。

しかし、Sandbox 環境用のコンソール画面はありませんので、API を用いてオペレーターを作成していただく必要があります。 以前は通常のサインアップ API を呼び出していただいていたのですが、手順が煩雑だったので、簡単にサインアップが完了する API を新たにご用意いたしました。 は以下のように /v1/sandbox/init API を呼び出すことでオペレーターを作成してください。

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{ "email": "email@example.com", "password": "superStrongP@ssw0rd", \
     "authKeyId": "<本番環境の SAM ユーザーの 認証キーID>", "authKey": "<本番環境の SAM ユーザーの認証キーシークレット>" }' \
     https://api-sandbox.soracom.io/v1/sandbox/init

# Response:
# 201 Created
# {
#   "operatorId": "OPXXXXXXXXXX",
#   "apiKey": "<ランダムな文字列>",
#   "token": "<ランダムな文字列>"
# }

ここで使用するメールアドレスは毎回異なるものを使用してください。Gmail を使用している場合、username+<ランダムな文字列>@gmail.com というように、ユーザー名の後ろに + 記号で好きな文字列を付け加えることができますのでそういった機能を利用するとよいでしょう。

また、API の戻り値として API Key と API Token が返されます。以降の API 呼び出しには、この API トークンを使ってください。(API キーは変化しません)

この時点で架空の支払情報(テスト用のクレジットカード番号)が登録済みなので、以後は任意の API を呼び出すことができるようになっています。

3. 架空の SIM の作成と登録

API を呼び出すためには、API による操作対象の SIM が必要です。Sandbox 環境に SIM を登録しましょう。 SIM を登録するには IMSI とパスコードが必要です。 Sandbox 環境では、実際の SIM の情報を登録する代わりに、架空の SIM を生成してから登録するという手順を踏みます。

まずは以下の Sandbox 専用 API で架空の SIM を生成します。

curl -X POST \
     https://api-sandbox.soracom.io/v1/sandbox/subscribers/create

# Response:
# 200 OK
# {
#   "imsi": "生成された SIM の IMSI",
#   "msisdn": "生成された SIM の MSISDN",
#   "registrationSecret": "生成された SIM を登録するときに必要なパスコード",
#      :
# }

ここで作成した架空の SIM を、以下のように通常の API でアカウントに登録します。

curl -X POST \
     -H 'Content-Type: application/json' \
     -H 'X-Soracom-API-Key: </v1/sandbox/init で入手した API キー>'  \
     -H 'X-Soracom-Token: </v1/sandbox/init で入手した API トークン>' \
     -d '{"registrationSecret": "上で取得したパスコード"}' \
     https://api-sandbox.soracom.io/v1/subscribers/{上で生成した SIM のIMSI}/register

# Response:
# 200 OK
# {
#   "imsi": "登録された SIM の IMSI",
#   "msisdn": "登録された SIM の MSISDN",
#      :
# }

必要な SIM の枚数分だけ create -> register を繰り返してください。

ここまで準備できれば、SIM に対して様々な API を呼び出すことができます。

例として、今登録したばかりの SIM の一覧を取得してみましょう。

curl -X GET \
     -H 'Content-Type: application/json' \
     -H 'X-Soracom-API-Key: </v1/sandbox/init で入手した apiKey>' \
     -H 'X-Soracom-Token: </v1/sandbox/init で入手した token>' \
     https://api-sandbox.soracom.io/v1/subscribers

# Response:
# 200 OK
# [
#   {
#     "imsi": "00101xxxxxxxxxx",
#     "msisdn": "99xxxxxxxxxx",
#     "ipAddress": "10.xxx.xxx.xxx",
#     "operatorId": "OP00xxxxxxxx",
#     "apn": "soracom-sandbox.io",
#     "type": "s1.standard",
#      :
#   }
# ]

いかがでしょうか。 この他にも、SIM だけではなく Group や Event Handler など他の API ももちろん呼び出すことが可能です。

ぜひいろいろ試してみてください。

Sandbox API リファレンス

Sandbox 環境には、上記で見てきたように Sandbox 環境専用の API があります。 本番環境と共通の通常の API に関しては SORACOM API Reference を参照してください。

pagetop