curl コマンドを利用して API を呼び出す

このセクションでは、 API Key / API Token の取得と、SIM の情報取得を行う例を解説します。

ステップ 1: API Key, API Token を取得する

API キーと API トークンで説明したように、SORACOM API を呼び出すには基本的に API Key と API Token が必要です。まずは auth API を呼び出し、パスワード認証を行って API Key と API Token を取得します。

下記はルートアカウントのオペレーターについて API Key と API Token を取得する例です。

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

# Response:
# 200 OK
#
# {
#   "apiKey": "API Key",
#   "token": "API Token",
#   "operatorId": "当該OperatorのID"
# }

下記は SAM ユーザーの API Key と API Token を取得する例です。認証キー ID と認証キーシークレットの作成方法は SAM ユーザーを作成するをご参照ください。

$ curl  -X POST \
      -H "Content-Type: application/json" \
      -d "{\"authKeyId\": \"keyId-xxxxxxx\", \"authKey\": \"secret-xxxxxxx\"}" \
      https://api.soracom.io/v1/auth

# Response:
# 200 OK
#
# {
#   "apiKey": "API Key",
#   "token": "API Token",
#   "operatorId": "当該OperatorのID",
#   "userName": "SAMユーザー名"
# }

Response Code: 200 OK は、API 呼び出しが成功したことを示しています。また、Response Body には API Key, API Token が含まれています。

ここで得られた apiKey と token の文字列は、この後の API 呼び出しで使いますので、安全な場所に保管しておきます。 (基本的にはアクセス制御の行われている揮発性の記憶領域に入れておくのがよいでしょう。認証さえすればいつでも API Key と API Token は入手できるので、基本的にはクライアント側で永続的に保管しておく必要はありません。)

ステップ 2: API を呼び出し Subscriber の情報を取得する

次に、listSubscribers API を呼び出し、Subscriber の一覧を取得してみましょう。先ほど取得した API Key と API Token を、それぞれリクエストの X-Soracom-API-Key ヘッダーと X-Soracom-Token ヘッダーに指定して送信します。

$ curl  -X GET \
      -H "X-Soracom-API-Key: 先ほど取得した API Key" \
      -H "X-Soracom-Token: 先ほど取得した Token" \
      https://api.soracom.io/v1/subscribers

# Response:
# 200 OK
#
# [
#   {
#     "imsi": "44010xxxxxxxxxx",
#     "msisdn": "8180xxxxxxxx",
#       :
#   },
#   :
# ]

Operator に Subscriber が 1 つでも登録されていれば、上記のように Subscriber の一覧が JSON 形式で取得できます。

ステップ 3: API を呼び出し Subscriber の速度クラスを変更する

続いて、この JSON に含まれる IMSI (International Mobile Subscriber Identity: SIM の ID) を用いて、その SIM の速度クラスを変更してみましょう。

$ curl  -X POST \
      -H "X-Soracom-API-Key: 先ほど取得した API Key" \
      -H "X-Soracom-Token: 先ほど取得した Token" \
      -H "Content-Type: application/json" \
      -d "{\"speedClass\":\"s1.fast\"}" \
      https://api.soracom.io/v1/subscribers/${SIMのIMSI}/update_speed_class

# Response:
# 200 OK
#
# {
#   "imsi": "44010xxxxxxxxxx",
#   "msisdn": "8180xxxxxxxx",
#      :
#   "speedClass": "s1.fast",
#      :
# }

Response Code: 200 OK が返り、Response Body に含まれている SIM の速度クラスが変更されていることが確認できます。

Windows のコマンドプロンプト (cmd.exe) から API 呼び出しを行う場合、リクエストボディに JSON を指定する時に注意が必要です。コマンドプロンプトでは、"" (ダブルクォーテーション) で囲まれた文字列は "" 内の文字列だけが意味を持ち、文字列を囲んでいるダブルクォーテーションは削除されます。また、" 単体ではダブルクォーテーションの文字そのものとして解釈されます。

例えば、JSON {"key":"value"} を Windows のコマンドプロンプトでは "{"""key""":"""value"""}" と書きます。