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 環境でオペレータを作成する
    1. サインアップする
    2. サインアップトークンを取得する(同時に、本番環境にアカウントを持っていることを確認する)
    3. サインアップトークンを用いてサインアップを完了する
  3. Sandbox 環境にログインする
  4. Sandbox 環境に架空の支払情報を登録する
  5. Sandbox 環境で架空の SIM を作成し登録する

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

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

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

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

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

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

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

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

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

2-1. Sandbox 環境にサインアップする

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

しかし、Sandbox 環境用のコンソール画面はありませんので、まずは以下のように通常の API を呼び出すことでオペレーターを作成(サインアップ)してください。

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{ "email": "email@example.com", "password": "superStrongP@ssw0rd" }' \
     https://api-sandbox.soracom.io/v1/operators

# Response:
# 201 Created

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

2-2. サインアップトークンを取得

オペレーターが作成されると、本番環境ではメールにてサインアップ用のトークンが通知されますが、Sandbox 環境ではメールによる通知は行われません。その代わりに、サインアップトークンを取得するための Sandbox 専用 API を用意してあります。

ここで本番環境のアカウントを所有しているかどうかのチェックも合わせて行いますので、「1. 本番環境で SAM ユーザーを準備する」で作成した本番環境の SAM ユーザーの 「認証キーID」と「認証キーシークレット」を API の引数としてリクエストの Body に入れて送ります。

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

# Response:
# 200 OK
# {
#   "token": "<ランダムな文字列>"
# }

このトークンの取得では、オペレーター作成時のメールアドレスをキーにしています。このため、メールアドレスを推測されると他人にサインアップトークンを横取りされる恐れがあります。 通常はサインアップトークンを横取りされたても実害は無いと思いますが、気になる場合はメールアドレスの一部に十分長いランダムな文字列を使用するなどの対策を行ってください。

2-3. サインアップトークンを用いてサインアップを完了

サインアップトークンが取得できたら、通常の API を呼び出してサインアップトークンのベリファイを行います。

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{ "token": "<先ほど取得したトークン>" }' \
     https://api-sandbox.soracom.io/v1/operators/verify

# Response:
# 200 OK

ベリファイに成功するとオペレーターの作成が完了しますので、これ以降はこのオペレーターで認証を行い、SORACOM API を呼び出していただくことができます。

3. サインアップしたオペレーターで認証

サインアップが完了したら、Sandbox 環境にログインします。そのために /v1/auth API で認証を行い、API キーと API トークンを取得しましょう。

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{ "email": "email@example.com", "password": "superStrongP@ssw0rd" }' \
     https://api-sandbox.soracom.io/v1/auth

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

4. 架空の支払情報の登録

ここまでの手順でオペレーターの作成および認証ができましたが、この段階ではまだ SIM が一枚も登録されていません。SIM がないと、呼び出すことができる API が限られてしまいます。そこで SIM を登録していきたいところですが、支払情報の登録が完了していない場合 SIM の登録ができませんので先に支払情報の登録を行います。とはいっても、本当のクレジットカードの番号を登録する必要はなく、カード番号は WebPay のページ に示されているようなテスト用のカード番号を使ってください。

curl -X POST \
     -H 'Content-Type: application/json' \
     -H 'X-Soracom-API-Key: <認証して入手した API Key>' \
     -H 'X-Soracom-Token: <認証して入手したトークン>' \
     -d '{ "cvc": "123", "expireMonth": 12, "expireYear": 2021, "name": "SORAO TAMAGAWA", "number": "4242424242424242" }' \
     https://api-sandbox.soracom.io/v1/payment_methods/webpay

# Response:
# 200 OK

支払情報を登録したら、API トークンを更新する必要があります。新しいトークンを生成するための API もありますが、ここでは簡単に /v1/auth で再度認証しましょう。

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{ "email": "email@example.com", "password": "superStrongP@ssw0rd" }' \
     https://api-sandbox.soracom.io/v1/auth

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

以降の API 呼び出しには、この取り直した API トークンを使ってください。(API キーは変化しません)

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

支払情報の登録ができたらようやく 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/auth で入手した API キー>'  \
     -H 'X-Soracom-Token: </v1/auth で入手した 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 だけではなく Group や Event Handler など他の API も呼び出すことが可能です。

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

Sandbox API リファレンス

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

pagetop