SORACOM, INC.

User Console »
Documents

SORACOM API 利用ガイド

SORACOM では、Air SIM など各種サービスの操作をAPIから行うことができます。このガイドでは、SORACOM APIに関する用語や概念と、API の基本的な利用方法を解説します。

用語と概念

SORACOM プラットフォームの用語では、電気通信事業者としてのアナロジーが使われています。

API を用いて管理する対象の SIM のことを Subscriber(サブスクライバー)と呼び、 Subscriber を所有するアカウントのことを Operator(オペレーター)と呼びます。SORACOM ユーザーコンソールでログインする際のアカウントが Operator に相当します。

ひとつの Operator は複数の Subscriber を所有することができます。Subscriber をまとめて管理する単位を Group(グループ)と呼び、Operator は複数の Group を所有することができます。SORACOM Beam など、各種サービスの設定は Group 単位で適用され、同じグループに所属する Subscriber すべてにその設定が反映されます。Subscriber は最大で 1 つの Group に所属することができます。(どの Group にも所属しなくても問題ありません)

Air SIM (Subscriber) には、日本国内向け Air SIM と、海外でも使えるグローバル向け Air SIM の2種類があります。Air SIMのサービス提供エリアは Coverage Type(カバレッジタイプ)と呼び、日本向けのものを Japan Coverage(ジャパン・カバレッジ)、グローバル向けのものを Global Coverage(グローバル・カバレッジ)と呼びます。Coverage Type は SIM の購入時点から固定で、後で切り替えることはできません。

ここまでに出てきた用語を図にまとめると以下のようになります。

SORACOMプラットフォームの用語とガイド

API Key と API Token

SORACOM API では、基本的に API 呼び出しの際に API Key と API Token という 2 種類のデータが必要です。

※例外として、パスワード認証を行い API Key と API Token を発行する API と、パスワードリセットを行う API は API Key と API Token が不要です。

API Key

API Key は Operator を識別するためのユニークなキーです。API Key を元にアクセス制御が行われるため、他人に知られないよう秘密にしておく必要があります。

API Token

API Token は API による操作のセッションを識別するためのユニークなキーです。新たな API セッションを開始するときには、その都度取得する必要があります。

API Token には有効期限があり、その有効期限を過ぎると使用できなくなります。既存の API セッションを継続するには、有効期限を超える前に、generateAuthToken API を呼び出して API Token を更新してください。一度 API Token の有効期限が切れてしまった場合は、再び認証処理を行い、新しい API Token を取得する必要があります。

API Token の有効期間は、API Token を取得する際に指定することができます。有効期間はデフォルトでは24時間で、最長で48時間まで指定できます。

有効期間を短く設定すると、万が一 API Token が漏洩してしまった場合の被害を抑えることに役立ちますが、あまりにも短すぎると利便性が落ちてしまいます。システムの要件に応じて有効期間を選んでください。例えば、一度実行したら API を一つだけ呼び出して数秒で終了してしまうような CLI スクリプトであれば有効期間は余裕を見ても1分程度で十分かもしれませんし、人間がインタラクティブに操作する GUI アプリケーションであれば無操作期間が30分〜1時間程度続いたら有効期間が切れるようにするのがちょうど良いかもしれません。

カバレッジタイプ

SORACOM プラットフォームは、主に SIM カードの使えるエリアの違いにより、カバレッジタイプという概念を導入しています。また、各サービスの接続拠点として使われる場所を ランデブーポイント と呼びます。

現時点では、以下の2種類のカバレッジタイプが用意されています。

  1. カバレッジタイプ Japan

    SORACOM Air の日本でのサービス開始当初からご提供している SIM で利用可能なカバレッジタイプです。 SIM は日本国内においてのみ利用可能です。ランデブーポイントは Tokyo で、Canal/Direct/Door/Gate といったプライベート接続サービスは AWS 東京リージョン (ap-northeast1) で接続されます。 Beam/Funnel の接続元も AWS 東京リージョンとなります。

  2. カバレッジタイプ Global

    カバレッジタイプ Global の SIM は、世界の120を超える国や地域で利用可能です。 ランデブーポイントは Frankfurt で、Canal/Direct/Door/Gate のプライベート接続サービスは AWS フランクフルトリージョン (eu-central-1) で接続されます。 Beam/Funnel の接続元も AWS フランクフルトリージョンとなります。

それぞれのカバレッジタイプ用に個別の API エンドポイントがありますので、操作対象のカバレッジタイプに応じて適切な API エンドポイントを使用してください。

カバレッジタイプ Japan および Global どちらの API エンドポイントでもアカウントのパスワード認証が可能で、取得された API Key や API Token はどちらのエンドポイントに対しても利用可能です。すなわち、API を呼び出したいアカウントがどちらのカバレッジタイプに対応したものか事前にわからなくても、アカウントの認証を行うことができます。

認証の結果得られた API Token には、そのアカウントで利用できるカバレッジタイプの情報が含まれています。API Token(JWT 形式)の Payload の Private claim operator.coverageType の内容を参照してください。

例えば、JavaScript で API Token からカバレッジタイプを取り出す際のコード例は以下のとおりです。

// token には /v1/auth API からのレスポンスに含まれる API Token の文字列が入っています
var parts = token.split('.');
var claims = JSON.parse(atob(unescape(encodeURIComponent(parts[1]))));
console.log(claims.operator.coverageTypes);
# => ["jp","g"]

operator.coverageTypes は、上の例のように文字列の配列形式で格納されています。

注意
このセクションで紹介したコード例はあくまでサンプルです。実際のシステムで API Token を利用する際には API Token の署名の検証を行ってください。また、エラー処理も正しく行ってください。

日付・時刻について

SORACOM の API では、日付と時刻のタイムゾーンは全て UTC(協定世界時)として扱われます。

API パラメータでは、UNIX Time(1970年1月1日からの経過秒数)を指定する箇所と、YYYYMMDD のようなフォーマットの文字列形式で指定する箇所がありますが、いずれも UTC で指定します。日本時間と時差があることに注意してください。例えば、日本時間で 10月1日 午前0時 を表現したい場合は、 UTC では 9月30日 午後3時となります。

ユーザーコンソールでは、お客様が分かりやすいように基本的に現地時間で日時を表記しているため、 API も 現地時間に準拠しているように感じられることがあるかもしれませんが、API はあくまでも UTC に準拠している点に注意してください。

エラーメッセージのフォーマット

SORACOM の API は、エラー発生の際には基本的に統一的なフォーマットに則ってエラーメッセージを返すようになっています。(一部、API サーバーに入る前のロードバランサーなどの部分が返すエラーメッセージを除きます)

SORACOM API が返すメッセージは JSON 形式で以下のような構成になっています。

{
    "code": "ABC1234",
    "message": "Description of the error"
}

code はこのエラーに割り当てられた識別コードで、message はエンドユーザに提示するためのエラーメッセージです。

API 呼び出しリクエストのヘッダーに X-Soracom-Lang: を含めると、その言語コードに対応している場合はエラーメッセージもその言語になります。(未対応の言語に対しては英語にフォールバックします)

現在対応している言語は en(英語), ja(日本語) の 2 つです。

サポート窓口への問い合わせの時は、事象の詳細と合わせて、エラーメッセージをご連絡いただくと問題解決に役立つ場合があります。

API 呼び出し例

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

1. API Key, API Token の取得

API Key, API Token の項でも説明したように、SORACOM API を呼び出すには基本的に API Key と API Token が必要です。まずは auth API を呼び出し、パスワード認証を行って 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 - ランダムな文字列",
#   "operatorId": "OPで始まる10桁程度の文字列",
#   "token": "API Token - ものすごく長いランダムな文字列"
# }

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 形式で取得できます。

続いて、この 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”“”}“ と書きます。

API リファレンス

SORACOM API の一覧は API リファレンスに掲載しています。また、FAQ には、よくあるご質問をまとめています。ぜひご覧ください。

pagetop