おんどとりWebStorageで管理されている機器の現在値グラフデータを取得します。
取得するグラフデータについて、期間・件数を指定することにより、より細かなグラフデータの取得が可能です。
https://api.webstorage.jp/v1/devices/data-rtr500
参照専用IDでもご利用できます。
※ RTR500Bシリーズの親機からFTPにてデータ送信している場合、こちらのAPIはご利用できません。
※ RTR500BCを親機としてご利用の場合、こちらのAPIはご利用できません。
20回/60秒、もしくは 160,000件/3600秒/機器毎
このAPIは比較的長めの間隔で、定期的にデータを取得することを想定して設計しています。
取得するデータ件数が多く負荷が高い処理であるため、同一機器に対して何度も重複するデータ取得が発生しないように機器ごとのデータ件数上限を設定し、かつ短期的な負荷を軽減するための最大アクセス回数を少な目に設定しております。ご了承ください。
短い間隔で最新のデータを確認したい場合には、下記APIをご利用ください。
項目名 | 値 |
---|---|
HTTP Method | POST |
X-HTTP-Method-Override | GET |
Host | api.webstorage.jp:443 |
Content-Type | application/json |
パラメータ名 | 型 | 要否 | デフォルト値 | 説明 |
---|---|---|---|---|
api-key | string(45文字) | 必須 | --- | 取得済みのAPI KEY |
login-id | string(8文字) | 必須 | --- | 利用者ID。参照専用IDでも可。 |
login-pass | string(4~16文字) | 必須 | --- | 上記利用者IDに対するパスワード。 |
remote-serial | string(8文字) | 必須 | --- | グラフデータを取り出す子機シリアル番号。複数台指定はできません。(*1) |
base-serial | string(8文字) | 必須 | --- | 上記の子機が登録されている親機シリアル番号。複数台指定はできません。(*2) |
unixtime-from | number | --- | グラフデータを取り出す先頭時刻のunixtime。(*3) 指定された時刻より新しい時刻のデータを取得します。 | |
unixtime-to | number | APIへアクセスした時刻 | グラフデータを取り出す最終時刻のunixtime。(*3) 指定された時刻未満の時刻のデータを取得します。 | |
number | number | 16000 | グラフデータを取り出す件数を指定する場合に利用。 デフォルトは16,000件、上限は65,535件。(*3) | |
type | string( json/csv/csv2 ) | json | 受け取るグラフデータの形式。json形式とcsv形式を選択できます。(*4) |
(*1) RTR-500シリーズ/RTR500Bシリーズの子機を指定可能です。
(*2) RTR500BW/RTR500BMのみ指定可能です。(RTR500BCはこちらのAPIは利用できません)
(*3) unixtime-from/unixtime-to/numberの指定について
・numberとして65,535以上を指定しても65,535に制限されます。
・unixtime-from/unixtime-toの指定はAND条件となり、新しい時刻のデータから順にnumber件数分のデータを取得します。
・unixtime-from、unixtime-toそしてnumberを指定しない場合は、直近の16,000件分のデータを取得することになります。
・unixtime-fromとunixtime-toに含まれるデータ件数がnumberで指定されたデータ件数よりも多い場合、期間に含まれるすべてのデータではなく、unixtime-toを起点として新しい方から順にnumber件数分のみ取得されます。
(例:unixtime-fromとunixtime-toによる期間指定で20,000件の対象データがある場合にnumberとして16,000件指定している場合には、unixtime-toを起点として時刻が新しい方から順に16,000件のデータを取得し、時刻が古い方の4,000件は取得しません。)
・unixtime-fromとunixtime-toに含まれるデータ件数がnumberで指定されたデータ件数よりも少ない場合、unixtime-fromからunixtime-toまでのデータが全て取得されます。
(例:unixtime-fromとunixtime-toによる期間指定で10,000件の対象データがある場合にnumberとして16,000件指定している場合には、unixtime-fromからunixtime-toの間のデータ10,000件を取得します。)
(*4) type=csvを設定した場合、json_encodeされた値がCSV形式で返ります。type=csv2を設定することで、CSV形式のレスポンス例と同じ形式の値を返します。
リクエストヘッダ
POST /v1/devices/data-rtr500 HTTP/1.1 Host: api.webstorage.jp:443 Content-Type: application/json X-HTTP-Method-Override: GET
リクエストボディ
[1.親機RTR500BW(sn:58580001)に紐付いているRTR-502(sn:52BA0001)の現在値グラフデータを新しい方から16,000件をjson形式で取得する場合] { "api-key":"73pfobnche8d1p6laqnemsbnpkght3bjv047oid6p2sg3", "login-id":"tbzz9999", "login-pass":"ppaasswwoorrdd", "remote-serial":"52BA0001", "base-serial":"58580001" } ※この例では、親機RTR500BW(sn:58580001)に紐付いているRTR-502(sn:52BA0001)の現在値グラフデータを新しい方から16,000件をjson形式で取得。 [2.親機RTR500BW(sn:58580001)に紐付いているRTR-502(sn:52BA0001)の現在値グラフデータを、2017年8月1日00:00:00~2017年9月1日00:00:00、 すなわち2017年8月分のデータを新しい方から16,000件分(該当期間のデータにより件数は変わります)をjson形式で取得する場合] { "api-key":"73pfobnche8d1p6laqnemsbnpkght3bjv047oid6p2sg3", "login-id":"tbzz9999", "login-pass":"ppaasswwoorrdd", "remote-serial":"52BA0001", "base-serial":"58580001", "unixtime-from":1504191600, "unixtime-to":1504191600 }
WindowsやMac端末などのコマンドラインから利用可能なcurlコマンドを使ったリクエスト例です。リクエストヘッダとリクエストボディを含む形でのコマンド例になっています。
[1.親機RTR500BW(sn:58580001)に紐付いているRTR-502(sn:52BA0001)の現在値グラフデータを新しい方から16,000件をjson形式で取得する例] curl -X POST \ -H "Content-Type: application/json" \ -H "X-HTTP-Method-Override: GET" \ -d '{"api-key":"73pfobnche8d1p6laqnemsbnpkght3bjv047oid6p2sg3","login-id":"tbzz9999","login-pass":"ppaasswwoorrdd","remote-serial":"52BA0001","base-serial":"58580001"}' \ https://api.webstorage.jp:443/v1/devices/data-rtr500 [2.親機RTR500BW(sn:58580001)に紐付いているRTR-502(sn:52BA0001)の現在値グラフデータを、2017年8月1日00:00:00~2017年9月1日00:00:00、 すなわち2017年8月分のデータを新しい方から16,000件分(該当期間のデータにより件数は変わります)をjson形式で取得する例] curl -X POST \ -H "Content-Type: application/json" \ -H "X-HTTP-Method-Override: GET" \ -d '{"api-key":"73pfobnche8d1p6laqnemsbnpkght3bjv047oid6p2sg3","login-id":"tbzz9999","login-pass":"ppaasswwoorrdd","remote-serial":"52BA0001","base-serial":"58580001","unixtime-from":1504191600,"unixtime-to":1504191600}' \ https://api.webstorage.jp:443/v1/devices/data-rtr500
項目名 | 値 | 説明 |
---|---|---|
HTTP status code | (**) | HTTPステータスコード |
Content-Type | application/json; charset=utf-8 text/csv; charset=utf-8 | JSON形式/CSV形式のいずれか指定した形式により変わる。文字コードはUTF-8。 |
X-RateLimit-Limit | (integer) | 単位時間あたりのアクセス上限 |
X-RateLimit-Reset | (integer) | 単位時間の秒数 |
X-RateLimit-Remaining | (integer) | 単位時間あたりのアクセス残数 |
X-RateLimit-Remaining-DataCount | (integer) | アクセス可能なデータ件数の残数 |
(**) HTTPステータスコードが「200」であれば正常に処理が完了しています。それ以外のHTTPステータスコードが返ってきた場合にはエラーにより処理されていません。 エラー発生時には下記のようなエラー情報を含むJSONデータが返ってきます。
HTTP/1.1 400 Bad Request Server: api.webstorage.jp Content-Type: application/json; charset=utf-8 X-RateLimit-Limit: 60 X-RateLimit-Reset: 60 X-RateLimit-Remaining: 57 X-RateLimit-Remaining-DataCount: 0 { "error":{ "code": エラーコード, "message": "エラーの内容" } }
下記の表において、channel.nameのように項目名にピリオド(.)が含まれるような場合は、channelに含まれる配列の要素を示しています。
項目名 | 型 | 説明 |
---|---|---|
remote-serial | string | 指定した子機のシリアル番号 |
remote-model | string | 指定した子機のモデル名称 |
remote-name | string | 指定した子機の機器名称 |
base-serial | string | 指定した親機のシリアル番号 |
base-model | string | 指定した親機のモデル名称 |
base-name | string | 指定した親機の機器名称 |
time-diff | string (*1) | 親機に設定されている時差情報[単位は分]。 |
std-bias | string (*1) | 親機に設定されている標準時差[単位は分]。 |
dst-bias | string (*1) | 親機に設定されている夏時間時差[単位は分]。 |
channel | 配列 | 測定チャンネル情報。データが不足している機器を指定した場合には空配列となる場合があります。 |
channel.name | string | チャンネル名称(*2) |
channel.num | string (*1) | チャンネル番号 (1 ~ 4) (*3) |
channel.unit | string | チャンネル測定単位 |
data | 配列 | データ件数0件の場合には空配列となります。 |
data.unixtime | string (*1) | グラフデータのunixtime |
data.data-id | string (*1) | グラフデータのdata-id (*4) |
data.ch1 | string (*1)(*5) | 上記unixtimeにおけるch1の値 |
data.ch2 | string (*1)(*5) | 上記unixtimeにおけるch2の値。機器によりch2を測定していない場合には存在しません。 |
data.ch3 | string (*1)(*5) | 上記unixtimeにおけるch3の値。機器によりch3を測定していない場合には存在しません。 |
data.ch4 | string (*1)(*5) | 上記unixtimeにおけるch4の値。機器によりch4を測定していない場合には存在しません。 |
(*1) 値は数値ですが、型は文字型となっています。
(*2) RTR500Bシリーズ/RTR-500シリーズの子機はチャンネル名称を設定できないため、「ch+チャンネル番号」が入ります。
(*3) RTR-574の場合、ch5とch6に積算照度・積算紫外線量のデータがありますが、こちらのAPIでは利用することはできません。
(*4) data-idは0-65535までの連続するIDとなり、65535を超えると0に戻ります。この値とunixtimeを用いることでデータの連続性をチェックすることができます。現在値データを受信できていない期間がある場合は、その期間のdata-idが抜けている場合があります。また、RTR500Bシリーズの場合は記録データとして送信するTRZ形式のデータにもdata-idが含まれていますが、こちらのAPIで取得可能なdata-idとは連動しておりませんのでご注意ください。
(*5) 計測値が取得できた場合は文字型の数値が返りますが、エラーが発生している場合はEから始まるエラー値が返ります。
※実際のレスポンスは下記の例のように見やすい形に整形されていない場合がありますのでご了承ください。
HTTP/1.1 200 OK Server: api.webstorage.jp Content-Type: application/json; charset=utf-8 X-RateLimit-Limit: 60 X-RateLimit-Reset: 60 X-RateLimit-Remaining: 57 X-RateLimit-Remaining-DataCount: 87654 { "remote-serial": "52BC0001", "remote-model": "RTR-503", "remote-name": "東側の窓の外", "base-serial": "58580001", "base-model": "RTR500BW", "base-name": "社屋東側", "time-diff": 540, "std-bias": 0, "dst-bias": 0, "channel":[ { "name":"ch1", "num":1, "unit":"C" },{ "name":"ch2", "num":2, "unit":"%" }], "data":[ { "unixtime": 1234560000, "data-id":101, "ch1":23.5, "ch2":65 },{ "unixtime": 1234560030, "data-id":102, "ch1":25.5, "ch2":68 }, ... ,{ "unixtime": 1235040000, "data-id":16100, "ch1":21.5, "ch2":60 } ] }
CSV形式でデータを受け取る際のデータ形式についての説明です。
この形式はT&D GraphなどでデータをCSV出力する形式と同じです。
1行目 (ヘッダ行) | Date/Time (固定値) | Date/Time (固定値) | No.1 (固定値) | No.2 (固定値) (チャンネル数により増減) |
No.3 (固定値) (チャンネル数により増減) |
No.4 (固定値) (チャンネル数により増減) |
---|---|---|---|---|---|---|
2行目 (ヘッダ行) | 時差:GMT**:**/夏時間:on/off (*1) (機器の時差設定) |
日付のシリアル値(Excel) (固定値) | ch1のチャンネル名称 | ch2のチャンネル名称 (チャンネル数により増減) |
ch3のチャンネル名称 (チャンネル数により増減) |
ch4のチャンネル名称 (チャンネル数により増減) |
3行目 (ヘッダ行) | (固定値で空データ) | (固定値で空データ) | ch1の測定単位 | ch2の測定単位 (チャンネル数により増減) |
ch3の測定単位 (チャンネル数により増減) |
ch4の測定単位 (チャンネル数により増減) |
4行目以降 (データ行) | 測定時刻 (*2) | 測定時刻のexcelのシリアル値 (*3) | ch1の測定値 | ch2の測定値 (チャンネル数により増減) |
ch3の測定値 (チャンネル数により増減) |
ch4の測定値 (チャンネル数により増減) |
(*1) 機器に設定されている時差情報と、WebStorageの管理画面上の夏時間設定のOn/Offが表示されます。
(*2) 測定時刻に機器の時差情報・夏時間補正を加えた時刻を"yyyy-mm-dd HH:mm:ss"の形式で表現しています。
(*3) (*2)の時差情報などで補正された時刻を、エクセルで利用される日付のシリアル値に変換したものです。
HTTP/1.1 200 OK Server: api.webstorage.jp Content-Type: text/csv; charset=utf-8 X-RateLimit-Limit: 60 X-RateLimit-Reset: 60 X-RateLimit-Remaining: 57 X-RateLimit-Remaining-DataCount: 87654 "Date/Time","Date/Time","No.1" "時差:GMT+9:00/夏時間:off","日付のシリアル値(Excel)","ch1" "","","C" "2016-12-14 15:46:14","42718.657106481","24.1" "2016-12-14 15:46:24","42718.657222222","24.0" "2016-12-14 15:46:34","42718.657337963","24.0" "2016-12-14 15:46:44","42718.657453704","24.1" "2016-12-14 15:46:54","42718.657569444","24.1" "2016-12-14 15:47:04","42718.657685185","24.0" "2016-12-14 15:47:14","42718.657800926","24.0" "2016-12-14 15:47:24","42718.657916667","24.0" "2016-12-14 15:47:34","42718.658032407","24.0" "2016-12-14 15:47:44","42718.658148148","24.1" "2016-12-14 15:47:54","42718.658263889","24.2" "2016-12-14 15:48:04","42718.65837963","24.2" .....