ファストセンシングについて
ファストセンシングは、データ監視・記録に必要な汎用的な機能を提供するIoTデバイス向けのクラウドツール群です。クラウド側の開発をすることなく、ネットワークとセンサを組み合わせたデータモニタリングシステムを構築できます。詳しくはファストセンシングのWebページをご覧ください。
この文書では、ファストセンシングに対応したIoTデバイス(以下、センサデバイス・デバイスと言います)を開発するためのAPI仕様について記述します。
はじめに
ファストセンシングのリソース構成
ファストセンシングでは、すべてのデバイスを1つのDeviceに複数のChannelがひもづくデータモデルとして扱います。Deviceはデバイスの1個体を表します。Channelはデバイスに搭載されるセンサ1個を表します。
例えば、温度センサおよび湿度センサを搭載したデバイスは、1つのDeviceに2個のChannelがひもづいた形として定義されます。また、10チャンネルの温度センサを搭載したデバイスは、1つのDeviceに10個のChannelがひもづいた形として定義されます。
デバイストークンとチャンネルトークン
前述のDeviceとChannelには、それぞれ固有の識別子(トークン)が発行されます。Deviceに対してデバイストークン、Channelに対してはチャンネルトークンが発行されます。実際のトークンは、ファストセンシングの管理画面の 「デバイス」タブ をクリックし、デバイス個別の画面から確認できます。
スタブデバイス
ファストセンシングに対応したデバイスを開発するには、ファストセンシング側にあらかじめデバイスのデータモデルを定義しておく必要があります。現在ファストセンシングでは、自作のデバイスを開発するエンジニアのために「スタブデバイス」を無償で提供しています。スタブデバイスは、1つのDeviceに3つのChannelを持つ仮想的なデバイスです。
スタブデバイスをアカウントに追加するには、スタブデバイスの追加ページに移動して、ボタンをクリックするだけです。
現在、1アカウントにつき5台までのスタブデバイスを所持できます。
APIのエントリポイント
ファストセンシングのAPIは、http/httpsプロトコルに準じた一般的なWebAPIです。エントリポイントは f-io.net/api
です。リクエストおよびレスポンスのテキストフォーマットはJSON形式です。メソッドはPOSTのみです。
なお、マイコンなどリソースの制約が厳しい環境向けに、一部機能を簡便なテキストプロトコルで利用可能にした「マイコンAPI」も提供しています。併せてご参考ください。
Channelへのデータの追加
デバイスからデータをアップロードする例を示します。
{
"api_version": "2016-05-02",
"resource_type": "channel_data",
"action": "update",
"device_token": "xxxxxxxxxxxxxxxx",
"resources": [
{
"token": "xxxxxxxx",
"value": 12.345
},
{
"token": "zzzzzzzz",
"value": 123.0
}
]
}
- api_version は "2016-05-02" 固定文字列です。
- resource_type は "channel_data" 固定文字列です。
- action は "update" 固定文字列です。
- device_token はデバイストークンを指定します。
- resources は登録したいデータを配列形式で指定します。1つのデータは"token"と"value"を含むオブジェクトにより定義されます。"token"には登録したいChannelのトークンを指定します。"value"には数値を指定します。
"resources"にはデバイスにひもづく全てのチャンネルのデータを含める必要はありません。例えば、3つのチャンネルを持つデバイスの場合でも、1つのチャンネルのデータだけをアップロードすることができます。
データのタイムスタンプは、APIサーバにリクエストが到達した時刻になります。1回のリクエストで3チャンネル分のデータを送信した場合、すべて同じタイムスタンプとなります。
もっともシンプルな登録例
curlコマンドによる登録の例です
% curl -I -H 'Content-type: application/json' -X POST -d '{ "api_version": "2016-05-02", "resource_type": "channel_data", "action": "update", "device_token": "xxxxxxxxxxxxxxxx", "resources": [ { "token": "xxxxxxxx", "value": 100.0 } ] }' http://f-io.net/api
タイムスタンプの明示的な指定
デバイスが時計機能を持つ場合、データのタイムスタンプを明示してアップロードすることもできます。タイムスタンプを明示するには、"time"キーにUNIX時刻を指定してください。
"resources": [
{
"token": "xxxxxxxx",
"value": 14.2,
"time": 1501053064
},
{
"token": "xxxxxxxx",
"value": 14.5,
"time": 1501053124
}
]
タイムスタンプで明示した時刻がAPIサーバの時刻と比べて24時間以上古い場合にはエラーとなりデータは登録されません。デバイス内蔵の時計が狂う可能性に留意してください。ファストセンシングのAPIサーバは、定期的に正確な時刻に同期しています。
同じタイムスタンプ・同じチャンネルトークンを持ったデータがすでに登録されている場合には、上書きされます。
レスポンス仕様
- 200 OK - 正常にリクエストを受け付けました.
- 404 Not Found - デバイスもしくはチャンネルが1つ以上見つかりませんでした。"device_token"もしくは"token"に正しいトークンが指定されているか確認してください。
- 415 Unsupported Media Type - HTTPリクエストにContent-type: application/jsonが含まれません
- 500 Request failed - 不正なJSONです (指定必須のキーがない、文法エラー、など)
API共通の制限事項
- 最小リクエスト間隔 5秒
- 最大リクエストボディサイズ 1,024バイト
注意
- デバイストークンおよびチャンネルトークンが流出すると第三者による意図しない操作が可能になります。取扱いには十分に注意してください。特に、ひとつのアカウントに複数のユーザを追加している場合、「管理者」権限のユーザはデバイストークンの閲覧が可能です。「管理者」権限は必要最低限のユーザに限定することをお勧めします。
- APIからのデータ削除は現在サポートされていません。Web管理画面より行ってください。
- 実時間より300秒以上過去のタイムスタンプを明示した場合には、モニタによる異常値の監視対象データとして扱われません。
Comments