api
IoT
fastsensing
@fastsensing

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

apiIoTfastsensing
More than 1 year has passed since last update.

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

ファストセンシングは、データ監視・記録に必要な汎用的な機能を提供する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",
      "resource": [
        { 
          "token": "xxxxxxxx",
          "value": 12.345  
        },
        { 
          "token": "zzzzzzzz",
          "value": 123.0     
        }
      ]
    }
  • api_version は "2016-05-02" 固定文字列です。
  • resource_type は "channel_data" 固定文字列です。
  • action は "update" 固定文字列です。
  • device_token はデバイストークンを指定します。
  • resource は登録したいデータを配列形式で指定します。1つのデータは"token"と"value"を含むオブジェクトにより定義されます。"token"には登録したいChannelのトークンを指定します。"value"には数値を指定します。

"resource"にはデバイスにひもづく全てのチャンネルのデータを含める必要はありません。例えば、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", "resource": [ { "token": "xxxxxxxx", "value": 100.0 } ] }' http://f-io.net/api

タイムスタンプの明示的な指定

デバイスが時計機能を持つ場合、データのタイムスタンプを明示してアップロードすることもできます。タイムスタンプを明示するには、"time"キーにUNIX時刻を指定してください。

一部のみ
"resource": [ 
  {
    "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