APIリファレンス (V2.0.0)
- Toru Murasawa
ここでは、ThingScaleのREST APIを使う上での基本的な決まりを解説します。
用語の説明
デバイス
デバイスはワイヤレスセンサネットワークのゲートウェイかエンドデバイス（センサノード）を意味します。
基本的にデバイスは手動登録されますが、自動的に登録（オートプロビジョニング）する事も可能です。
いずれの場合もデバイス作成後はチャネルにマップする必要が生じます。
手動登録
例：管理コンソールから手動でデバイスIDを登録した場合自動登録（オートプロビジョニング）
例：正しく設定済みのデバイスを初めてThingScaleプラットフォームに接続した場合
デバイスの内容はdevice serviceにより取得することができます。
チャネル
Channel（チャネル）はデバイスからのデータを蓄積する論理チャネルです。
デバイスから直接チャネルを指定する事はなく、デバイスID（デバイスシリアル）とマップされたチャネルにデータが蓄積されます。
チャネルはスキーマレスなJSONオブジェクトを格納可能な時系列データベースです。それぞれのストリームはラベルと単位を指定することが可能です。
チャネルの内容はchannel serviceにより取得することができます。
ストリーム
Stream（ストリーム）はデバイスが送信したセンサデータです。（例：温度情報）
ストリームは数値または文字列です。
データフォーマートはJSONオブジェクト形式で記述する必要があります。
NOTE
文字列はUTF-8でエンコードされている必要があります。
Data type sample:
12.5 : 数値(float)
"Hello!" : 文字列(string)
{"temp" : 25, "humidity" : 50} : JSONオブジェクト
メトリクスはStream serviceにより取得することができます。
APIについて
ThingScaleのRESTful APIはJSONベースのHTTPリクエスト（GET/POST/PUT/DELETE）により実装されています。
REST API（HTTP/HTTPSプロトコル）はアプリケーションから呼び出され、デバイスの管理や時系列データの読み取りを行います。
APIは用途により、以下が用意されています。
Device service:デバイスの管理・チャネル割り当て・アクティベーション
Channel service:ストリーム（時系列データ）格納チャネルの管理・メタデータ設定
Stream service:ストリームの参照・メタデータ設定
Event service:ストリーム処理（しきい値の設定・外部システムへの通知）の設定
User service:ユーザ情報(メールアドレス・トークン情報etc）の参照・設定
Publish service:デバイスへのパブリッシュ（MQTTメッセージのパブリッシュ）
Session service:アクティブなPub/Subセッションの表示
APIのバージョニング
APIバージョンはエンドポイントURIに規定されています。(e.g. https://m.thingscale.io/v2/<SERVICE_NAME>)
現在のAPIバージョン・リリースノートはRelease Noteを参照してください。
セキュリティ
全てのThingScaleとの通信はhttps(HTTP over TLS)により行われます。
これはThingScaleとデバイス、アプリケーション間の通信が暗号化されて行われる事を保証します。
HTTP/MQTTデバイスコネクタは非力なデバイス（ゲートウェイ含む）のために非暗号化接続も利用可能です。
HTTP/HTTPS(MQTT/MQTTS)接続は長所と短所を含みますが、お使いの環境に応じて最適な方法をセキュリティ上のトレードオフも考慮して選択してください。
通信経路上のセキュリティを確保するためにHTTPS/MQTTSによる暗号化接続を強く推奨します。
プロトコル | セキュリティ | デバイスに要求されるシステムリソース |
|---|---|---|
HTTP/MQTT | 脆弱（非暗号化接続） | 低い |
HTTPS/MQTTS | 堅牢（暗号化接続 - 第3者による中間攻撃を防ぐ） | 高い（より多くのメモリとCPU時間を必要とします。） |
トークン
トークンはユーザ毎に割り当てられたREST API/デバイスコネクタの認証キーです。
APIトークンを利用する全てのケースにおいて、HTTPS(TLS)接続を利用されることを強く推奨します。
APIトークン
全てのRESTful API操作においてAPIトークンが使用されます。デバイストークン
デバイスからプラットフォームへのデータ送信時（HTTP/MQTTデバイスコネクタ利用時）のみ利用されます。
NOTE
デバイストークンはデバイス単位ではなくユーザ単位に割り当てられます。これはデバイス配布時の設定タスク（デバイス毎のトークンの埋め込み作業）を簡略化するためです。
fig.2 トークン概略
トークンの役割：
トークンタイプ: | REST API | HTTP/MQTTデバイスコネクタ |
|---|---|---|
APIトークン | 必要 | - |
デバイストークン | - | 必要 |
データフォーマットと日付の取り扱い
全てのAPIリクエストとレスポンスはJSONペイロードにて通知されます。
HTTP/MQTTデバイスコネクタはURLエンコード形式のペイロードを利用します。
全てのタイムスタンプはUTC時間に対しての相対時間としてISO8601:2004形式として表記されます。
Sample
e.g. Stream response(TZ="Asia/Tokyo")
{"_id":"54d3fc256807f4a616acbb33","value":11.1,"value2":47.9,"value3":null,"value4":null,"at":"2015-02-06T08:26:29+0900"}e.g. Device list response(TZ="Asia/Tokyo")
{
"device_id": "1085266243",
"description": "sensirion sht-25",
"enable": "true",
"mapped_ch": 0,
"device_type": "Xbee Pro2",
"location": "Niigata,Japan",
"manufacturer": "Sensincs,llc",
"activate_at": "2015-01-13T16:58:00+09:00"
}APIレートリミット
API/HTTPデバイスコネクタ使用時は同一IPアドレスからの秒間あたりのAPIリクエスト数に応じてレートリミット（流量制御）が適用されます。
（MQTTデバイスコネクタにはレートリミットは適用されません）
現在のレートリミット上限は以下の通りです。
REST API
20 リクエスト/秒デバイスコネクタ(HTTP利用時のみ)
1 リクエスト/秒
On this page:
© 2014-2022 SENSINICS,LLC