Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
1
Help us understand the problem. What is going on with this article?
@fastsensing

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

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",
      "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秒以上過去のタイムスタンプを明示した場合には、モニタによる異常値の監視対象データとして扱われません。
1
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
1
Help us understand the problem. What is going on with this article?