Versions Compared

Old Version 10

changes.mady.by.user Toru Murasawa

Saved on

compared with

New Version Current

changes.mady.by.user Toru Murasawa

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

ここでは、ThingScaleのREST APIを使う上での基本的な決まりを解説します。

用語の説明

デバイス

デバイスはワイヤレスセンサネットワークのゲートウェイかエンドデバイス（センサノード）を意味します。

基本的にデバイスは手動登録されますが、自動的に登録（オートプロビジョニング）する事も可能です。

いずれの場合もデバイス作成後はチャネルにマップする必要が生じます。

  • 手動登録
    例：管理コンソールから手動でデバイスIDを登録した場合

  • 自動登録（オートプロビジョニング）
    例：正しく設定済みのデバイスを初めてThingScaleプラットフォームに接続した場合

デバイスの内容はdevice serviceにより取得することができます。

チャネル

Channel（チャネル）はデバイスからのデータを蓄積する論理チャネルです。

デバイスから直接チャネルを指定する事はなく、デバイスID（デバイスシリアル）とマップされたチャネルにデータが蓄積されます。

チャネルはスキーマレスなJSONオブジェクトを格納可能な時系列データベースです。それぞれのストリームはラベルと単位を指定することが可能です。

チャネルの内容はchannel serviceにより取得することができます。

ストリーム

Stream（ストリーム）はデバイスが送信したセンサデータです。（例：温度情報）

ストリームは数値または文字列です。

データフォーマートはJSONオブジェクト形式で記述する必要があります。

Tip

NOTE

文字列はUTF-8でエンコードされている必要があります。

Data type sample:

12.5 : 数値(float)

"Hello!" : 文字列(string)

{"temp" : 25, "humidity" : 50} : JSONオブジェクト

デバイス

デバイスはワイヤレスセンサネットワークのゲートウェイかエンドデバイス（センサノード）を意味します。

基本的にデバイスは手動登録されますが、自動的に登録（オートプロビジョニング）する事も可能です。

いずれの場合もデバイス作成後はチャネルにマップする必要が生じます。

  • 手動登録
    例：管理コンソールから手動でデバイスIDを登録した場合

    • 自動登録（オートプロビジョニング）
    例：正しく設定済みのデバイスを初めてThingScaleプラットフォームに接続した場合

    メトリクスはStream serviceにより取得することができます。

    APIについて

    ThingScaleのRESTful APIはJSONベースのHTTPリクエスト（GET/POST/PUT/DELETE）により実装されています。

    REST API（HTTP/HTTPSプロトコル）はアプリケーションから呼び出され、デバイスの管理や時系列データの読み取りを行います。

    APIは用途により、以下が用意されています。

    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)接続は長所と短所を含みますが、お使いの環境に応じて最適な方法をセキュリティ上のトレードオフも考慮して選択してください。

    Note

    通信経路上のセキュリティを確保するためにHTTPS/MQTTSによる暗号化接続を強く推奨します。

    プロトコル

    セキュリティ

    デバイスに要求されるシステムリソース

    HTTP/MQTT

    脆弱（非暗号化接続）

    低い

    HTTPS/MQTTS

    堅牢（暗号化接続 - 第3者による中間攻撃を防ぐ）

    高い（より多くのメモリとCPU時間を必要とします。）


    トークン

    トークンはユーザ毎に割り当てられたREST API/デバイスコネクタの認証キーです。

    APIトークンを利用する全てのケースにおいて、HTTPS(TLS)接続を利用されることを強く推奨します。

    • APIトークン
      全てのRESTful API操作においてAPIトークンが使用されます。

    • デバイストークン
      デバイスからプラットフォームへのデータ送信時（HTTP/MQTTデバイスコネクタ利用時）のみ利用されます。

    Tip

    NOTE

    デバイストークンはデバイス単位ではなくユーザ単位に割り当てられます。これはデバイス配布時の設定タスク（デバイス毎のトークンの埋め込み作業）を簡略化するためです。


    fig.2 トークン概略

    Image RemovedImage Added

    トークンの役割：

    トークンタイプ:

    REST API

    HTTP/MQTTデバイスコネクタ

    APIトークン

    必要

    -

    デバイストークン

    -

    必要


    データフォーマットと日付の取り扱い

    全てのAPIリクエストとレスポンスはJSONペイロードにて通知されます。

    HTTP/MQTTデバイスコネクタはURLエンコード形式のペイロードを利用します。

    全てのタイムスタンプはUTC時間に対しての相対時間としてISO8601:2004形式として表記されます。

    Tip

    NOTE

    ストリームの読み出し時のみ、時間範囲の指定はローカルタイムゾーンで行ってください。.(e.g. 'YYYY-MM-DD hh:mm')

    ISO8601:2004形式ではなく、 'YYYY-MM-DD hh:mm'形式で行ってください。

    Sample

    e.g. Stream response(TZ="Asia/Tokyo")
    Code Block
    languagejs
    {"_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")
    Code Block
    languagejs
    {
  "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デバイスコネクタにはレートリミットは適用されません）

    Tip

    NOTE

    単位時間あたりのリクエスト数が上限に達した場合、APIは'429 Too Many Requests'のステータスコードを返します。

    現在のレートリミット上限は以下の通りです。

    • REST API
      20 リクエスト/秒

    • デバイスコネクタ(HTTP利用時のみ)
      1 リクエスト/秒






    Panel

    On this page:

    Table of Contents