管理API 利用ガイド¶

ここでは、 sakura.io 管理APIの使い方について説明します。管理APIでは、モジュールの登録・解除、プロジェクトの作成・削除、連携サービスの作成・削除ができます。

用語¶

APIキー¶

API を操作するにあたって、 APIキー を作成する必要があります。アカウントに対して、複数のAPIキーが作成でき、APIキーごとに、操作権限(レベル )を持っています。

Token と Secret¶

実際にAPIを利用するに当たっては、APIキーごとに作成される、 Token と Secret が必要です。 TokenとSecretを用いてBasic認証を行うことで、認証を行います。

※Token, Secretは再作成できないため、もし再作成の必要が生じた場合には、APIキー自体を削除・作成してください。

APIキーの作成とToken, Secretの確認¶

APIキーの作成はsakura.ioコントロールパネルから行います。 APIキーメニューから、作成を行ってください。

注意事項

APIキーのTokenおよびSecretは認証および各操作を実現するための重要な情報です。SNSなどを通して第三者に共有しないでください。

API 呼び出し例¶

ここでは、いくつかの例を API を用いて実行してみます。

API 呼び出し例: プロジェクトのモジュール一覧¶

プロジェクトの一覧を取得し、モジュールを登録してみます。

APIキーを権限 全権限 として作成し、 Token と Secret を確認します。以下のドキュメントでは、それぞれ _token_, _secret_ と記載します。

API を用いて、プロジェクトの一覧を取得します。

$ curl -X GET --header 'Accept: application/json' --user '_token_:_secret_' 'https://api.sakura.io/v1/projects/'
[{"id":2,"name":"project02","options":{"datastore":"light","location":false}},{"id":1,"name":"project01","options":{"datastore":"light","location":false}}]

モジュールを project01 に登録します。登録するモジュールの登録用ID, PASSを _id_, _pass_ とします。 project01のidは1なので以下のようにします。

$ curl -X POST --header 'Accept: application/json' --user '_token_:_secret_' -d '{"register_id":"_id_","register_pass":"_pass_","name":"module_name","project":1}' 'https://api.sakura.io/v1/modules/'
{"id":"_id_","name":"module-name","project":1,"is_online":false,"serial_number":"xxxxxx","model":"SCM-LTE-01","points":0}

project01 に登録されているモジュールの一覧を取得します。

$ curl -X GET --header 'Accept: application/json' --user '_token_:_secret_' 'https://api.sakura.io/v1/modules/?project=1'
[{"id":"_id_","name":"moduel_name","project":1,"is_online":false,"serial_number":"xxxxxx","model":"SCM-LTE-01"}]

API 呼び出し例: 通信料の取得¶

ユーザの月間通信料を取得してみます。

APIキーを権限 全権限 もしくは 読み取り権限 として作成し、 Token と Secret を確認します。以下のドキュメントでは、それぞれ _token_, _secret_ と記載します。

API を用いて、対象の月の通信料を取得します。ここでは、2018年2月の通信料を取得します。 2018年2月は、201802 のフォーマットで表されます。

$ curl -X GET --header 'Accept: application/json' --user '_token_:_secret_' 'https://api.sakura.io/v1/report/?month=201802'
[{"from_module": 100, "to_module": 50, "file_distribution": 50, "projects": [ {"project_id": 3, "to_module": 50, "from_module": 100, "file_distribution": 50 }]}]

注釈

レスポンスパラメータについて

from_module は module から sakura.io への通信回数です。
to_module は sakura.io から module への通信回数です。
file_distibution は sakura.io から module へのファイル配信量(単位は byte) です。

API リファレンス¶

API の詳細については、 sakura.io APIリファレンスを参照ください。