Versions Compared

Key

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

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

用語の説明

デバイス

デバイスはServwatchの監視対象ホストの最小単位です。

基本的にデバイスはServwatchエージェントにより自動登録されますが、手動登録することも可能です。

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

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

  • 自動登録(オートプロビジョニング)
    例:エージェントがServwatchにデバイスを自動登録した場合

チャネル

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

チャネルIDは常に整数値で指定されます。

チャネルはスキーマレスなJSONオブジェクトを格納可能な時系列データベースです。

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

メトリクス

メトリクスはデバイス(サーバ)が送信した各種パフォーマンスデータです。(例:CPU idle)

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

Tip
title

NOTE

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

メトリクスはデバイスにマップされたチャネルID毎にストアされます。

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

APIについて

デバイス(サーバ)とServmetry間はMQTTプロトコルにより通信を行い、アプリケーションとServmetry間はHTTP(S)プロトコルを利用します。

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
title

NOTE

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


fig.2 トークン概略Image Removed

Image Added

トークンの役割:

トークンタイプ:

REST API

HTTP/MQTTデバイスコネクタ

APIトークン

必要

-

デバイストークン

-

必要


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

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

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

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


Tip
title

NOTE

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

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

Sample

Code Blocklanguagejstitle
e.g. Stream response(TZ="Asia/Tokyo")
language
Code Block
languagejs
{"_id":"54d3fc256807f4a616acbb33","value":11.1,"value2":47.9,"value3":null,"value4":null,"at":"2015-02-06T08:26:29+0900"}
Code Block
jstitle


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デバイスコネクタにはレートリミットは適用されません)

title
Tip

NOTE

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

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

  • REST API
    20 リクエスト/秒

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







Panel

On this page:

Table of Contents