@fastsensing
Edited at

ファストセンシングAPI仕様

apiIoTfastsensing


ファストセンシングについて

ファストセンシングは、データ監視・記録に必要な汎用的な機能を提供するIoTデバイス向けのクラウドツール群です。クラウド側の開発をすることなく、ネットワークとセンサを組み合わせたデータモニタリングシステムを構築できます。詳しくはファストセンシングのWebページをご覧ください。

この文書では、ファストセンシングに対応したIoTデバイス(以下、センサデバイス・デバイスと言います)を開発するためのAPI仕様について記述します。


はじめに


ファストセンシングのリソース構成

ファストセンシングでは、すべてのデバイスを1つのDeviceに複数のChannelがひもづくデータモデルとして扱います。Deviceはデバイスの1個体を表します。Channelはデバイスに搭載されるセンサ1個を表します。

resource.png

例えば、温度センサおよび湿度センサを搭載したデバイスは、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秒以上過去のタイムスタンプを明示した場合には、モニタによる異常値の監視対象データとして扱われません。

Edit request
3