Soracom

Users

開発者向けツール
Home 開発者向けツール SORACOM API 利用ガイド リファレンス

API リファレンスの使いかた

SORACOM API リファレンスで SORACOM API を呼び出す

SORACOM API リファレンス は、SORACOM API の仕様を確認できるだけでなく、実際に SORACOM API を呼び出すことができます。

ここでは、Sim:listSims API を例として、API リファレンスで SORACOM API を呼び出す操作を説明します。

SORACOM API リファレンスで SORACOM API を呼び出しても実際に効果を持ちます

たとえば、SORACOM Air for セルラーの IoT SIM を解約する SORACOM API を呼び出すと、実際に IoT SIM が解約されます。解約した IoT SIM は、すぐに通信できなくなります。また、ほかのステータスに変更することはできません。そのほか、課金が伴う SORACOM API も実行でき、実際に課金が発生します。

  • ルートユーザーのメールアドレスとパスワードを入力したり、ルートユーザーの認証キー ID と認証キーシークレットを入力したりすると、ルートユーザーとして SORACOM API を実行したことになります。
  • SAM ユーザーの認証キー ID と認証キーシークレットを入力すると、SAM ユーザーとして SORACOM API を実行したことになります。
開発目的で SORACOM API を試す場合は SORACOM API Sandbox を利用してください

SORACOM API Sandbox (以下、Sandbox) とは、SORACOM API の利用方法を学習したり、SORACOM API を試したりできる環境です。Sandbox で実行された SORACOM API は実際の IoT SIM には影響しないため、SORACOM API を呼び出すことが難しいような処理 (解約など) を試せます。詳しくは、SORACOM API Sandbox 利用ガイド を参照してください。

操作を始める前に準備が必要です (クリックして確認してください)

ルートユーザーの認証情報を利用できますが、安全のために SAM ユーザーを作成し、SAM ユーザーの認証キーと認証キーシークレットを取得することを推奨します。

(1) SAM ユーザーを作成する

SAM ユーザーを作成する を参照してください。

(2) SAM ユーザーの認証キーと認証キーシークレットを取得する

認証キーを生成する を参照してください。

準備完了
  1. SORACOM API リファレンス にアクセスして、注意事項をよく読み、[注意点を理解して認証する] をクリックします。

    注意点を理解して認証する 注意点を理解して認証する

  2. [認証キー ID] および [認証キーシークレット] を入力して、[認証] をクリックします。

    認証 認証

    [API キー][API トークン]、および [オペレーター ID] に、認証キーに対応した情報が表示されます。

    • [SORACOM アカウントのメールアドレスとパスワードを使用する] をクリックすると、ルートユーザーのメールアドレスとパスワードを入力して、API キーと API トークンを発行できます。その場合、SORACOM API リファレンスで呼び出した SORACOM API は、ルートユーザーの権限で実行されます。
    • これ以降、ブラウザで再読み込みを実行すると、手順 2 で表示された API キー、API トークン、オペレーター ID は破棄されます。
  3. [Sim][listSims][Try it out] の順にクリックします。

    listSims listSims

  4. [Parameters] の各項目を設定して、[Execute] をクリックします。

    listSims listSims

    SORACOM API が呼び出され、以下の項目が表示されます。

    項目説明
    [Executed command: Curl]手順 4 で呼び出した SORACOM API を、curl コマンドで実行する場合のコマンド例が表示されます。
    [Request URL]URL が表示されます。
    [Server response]実行結果 (HTTP レスポンスコード、Response body、Response headers) が表示されます。

    listSims listSims

SORACOM API リファレンスの読みかた

便利な機能や、分かりにくい箇所を抜粋して説明します。

SORACOM API の詳細の表示 / 非表示を一括で切り替える

[表示] / [非表示] をクリックすると、すべての SORACOM API の詳細の表示 / 非表示を一括で切り替えられます。

Parameters の読みかた

[Parameters] に、array[string](query) が同時に表示されている場合は、クエリに name=AAAA&name=BBBBB のように指定できます。

SORACOM API リファレンスの表示例:

URL の例:

https://api.soracom.io/v1/query/sims?name=AAAAA&name=BBBBB

name[0]name[1] のような添え字は不要です。

Request body の読みかた

[Request body] を指定できる API には、[Example Value][Schema] が表示されます。

  • [Example Value] には、[Schema] の内容から自動生成された例が表示されます。この例は、Request body のフォーマットを理解するためのものです。そのまま Request body に指定しても、API を呼び出すことができない場合があります。説明に従って、正しい Request body を指定してください。

    {
      "expiryAction": "doNothing",
      "expiryTime": 0
    }
    
  • [Schama] には、キー (例: expiryAction)、型 (例: string)、取りうる値 (Enum の場合) などが表示されます。

    この説明から、正しい Request body を指定してください。この API の場合は、以下のような JSON を Request body に指定することを表しています。

    {
      "expiryAction": "terminate",
      "expiryTime": 1672498800
    }