トップ > ブリ > SORACOMのAPIで遊んでみる

SORACOMのAPIで遊んでみる

ブリ
記事タイトルとURLをコピーする

この記事は SORACOM Advent Calendar 2016 の12/14分です。

みなさんこんにちは！

サーバーワークス IoT担当の中村です。
今日はSORACOMのAPIの話をします。

SORACOMは非常に多くの事をAPIから実行できるようになっています。料金の確認から、SIMの有効化、無効化、速度クラスの変更、さらにはSIMの注文までできます。
ドキュメントも非常に丁寧で、API Referenceのページからは実際にリクエストを投げることもできるようになっています。

API Reference https://dev.soracom.io/jp/docs/api/

というわけで、早速SORACOM APIを使ってみましょう。

APIを実行するための準備

まずは、APIを実行するための準備を行います。
はじめに、SORACOMのプラットフォーム用のユーザー(SAMユーザー)を作ってユーザーの認証キーを発行します。そしてロールを作成し、ユーザーに割り当てます。次に、認証キーを使ってAPIを実行するためのトークンを取得します。

SAMユーザーを作る

まずはSAMユーザーを作ります。SAMとはSORACOM Access Managamentの略で、AWSにおけるIAMユーザーのようなものです。

マネジメントコンソールの右上のボタンから「セキュリティ」を選択するとユーザーを作成することができます。

00-security

ユーザ作成後、認証キーを生成できるため、生成して控えておきましょう。

01-create-key

ロールを作ってユーザーに割り当てる

続いて、ロールを作りましょう。RoleはAWSにおけるPolicyのようなものです。許可する条件や動作をJSONで記載しておくことで、動作を制限することができるようになります。

02-create-role

今回はロールは以下のように設定します。このロールはGET、POST系のメソッドに限り、全てのAPIが実行できる設定です。APIのテストなので、削除系のAPIが実行されないようにDELETEメソッドを実行できないようにしています。

{
    "statements":[
        {
            "effect":"allow",
            "api":"*",
            "condition":"httpMethod('GET', 'POST')"
        }
    ]
}


ロールの構文については以下のページで詳しく説明されています。

アクセス権限設定のためのパーミッション構文 https://dev.soracom.io/jp/docs/sam_permission/

ロールを作成したら、先程作成したSAMユーザーに割り当てましょう。SAMユーザーの画面で、権限設定タブからロールをアタッチすることができます。

トークンを発行する

続いて、APIを叩くために必要なトークンを取得します。トークンは https://api.soracom.io/v1/auth に 認証キーIdと認証キーをPostすることで取得できます。

curlコマンドだと、こんな感じです。

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


リクエストが成功すると、以下のようなJSONが返ってきます。X-Soracom-API-KeyがAPIキーでX-Soracom-Tokenがトークンになっています。今後、APIを叩く際にはこの2つをヘッダーに含める必要があります。

{ Accept: 'application/json',
  'X-Soracom-API-Key': 'xxxxxxxxxx',
  'X-Soracom-Token': 'xxxxxxxxxxxxx....(とても長い)' }


ここで発行した認証情報はデフォルトで発行してから24時間有効で、最大48時間まで指定することができます。リクエストの中のtokenTimeoutSecondsが認証情報の有効時間ですね。単位は秒なので、この数字を調整することで、認証情報の有効時間を調整することができます。

SIM一覧を取得してみる

さて、APIを実行する準備が整ったところで、APIを実行してみましょう。

まずはSIMの一覧の取得方法です。これはとても簡単で、「https://api.soracom.io/v1/subscribers」にGETリクエストを投げるだけです。「subscribersって何？」と思うかもしれないですが、これはSIMカードの正式名称が「Subscriber Identity Module Card」によるものだと思います。

実際のリクエストはこんな感じです。

curl -X GET \
  -H 'X-Soracom-API-Key: xxxxxxxx' \
  -H 'X-Soracom-Token: xxxxxxxxxxxxxxxxxxxx' \
  https://api.soracom.io/v1/subscribers


リクエストが成功すると、以下のようなJSONが返ってきます。速度クラスやSIMのグループ、IPアドレス、セッションのステータス等を確認できることがわかります。また、パラーメーターを与えることで、条件にマッチしたSIMのみを取得することができます。例えば、アクティベート済み(利用中)のSIMを取得するには https://api.soracom.io/v1/subscribers?status_filter=active のようにパラメーターを付け加えます。

[
  {
    "imsi":"000000000000",
    "msisdn":"000000000000",
    "ipAddress":null,
    "operatorId":"000000000000",
    "apn":"soracom.io",
    "type":"s1.standard",
    "groupId":null,
    "createdAt":1465354302542,
    "lastModifiedAt":1481128105155,
    "expiredAt":null,
    "expiryAction":null,
    "terminationEnabled":false,
    "status":"active",
    "tags":{},
    "sessionStatus":null,
    "imeiLock":null,
    "speedClass":"s1.standard",
    "moduleType":"micro",
    "plan":0,
    "iccid":null,
    "serialNumber":"000000000000",
    "expiryTime":null,
    "createdTime":1465354302542,
    "lastModifiedTime":1481128105155
  },
  {
    "imsi":"000000000000",
    "msisdn":"000000000000",
    "ipAddress":null,
    ....
  }
]

 

ブリに仕込んでみる

上記のように、SORACOMのAPIを実行することができました。今回はSIM情報を取得するAPIを例に挙げましたが、他のAPIも同様に簡単に実行することが可能です。

APIを使えるようになったら、せっかくなので色々遊びたいですよね。というわけで、ブリに色々仕込んでみました。

今月の利用料金を聞く

03-bill

これは、 /bills/latest というAPIを利用しています。このAPIは無料利用枠などの割引適用後の、直近の利用額を返してくれます。利用料金をぱっと調べられるのは嬉しいですね〜。毎日でも聞いてしまいそうです。

使えるSIMがあるかどうか聞く

04-card

これは今回の記事でも試した /subscribers のAPIを使っています。このAPIで得られるJSONのsessionStatus属性には、利用した事があるSIMであれば、現在オンラインになっていなくてもオンラインになった履歴が残っています。逆に、利用したことがないSIMであれば null が入っています。そのため、sessionStatusがnull(利用した形跡がないSIM)の数を余っているSIMとして出しています。

「社内で検証したいけど余ってるSIMありますか？」という問い合わせは結構あるので、ブリに実装できて満足です。

SIMの速度クラスを変更する

05-change-speed
IMSIを指定して速く、遅く、と伝えると速度クラスを変更してくれる機能です。
こちらは /subscribers/{imsi}/update_speed_class APIを利用しています。

※ちなみに、IMSIとはInternational Mobile Subscriber Identityの略で、SIMカード1枚1枚に割り当てられているIDのことです。

まとめ

というわけで、今回はSORACOMのAPIを紹介しました。SORACOMはマネジメントコンソールやAPIの操作感がAWSに近いため、AWSを利用したことがある方であれば戸惑うこと無く利用できるのではないでしょうか。

実際にAPIを使ってみた感想としては、ドキュメントやエラーメッセージがとても丁寧な印象を受けました。また、HTTPSリクエストを投げる際にAWSのような複雑な署名が必要ないのも良いですね。お手軽です。