おんどとりWebStorageで管理されている機器の現在値グラフデータの中で最新部分300件を取得します。
https://api.webstorage.jp/v1/devices/latest-data
参照専用IDでもご利用できます。
60回/60秒
10数台規模で、対応機器を最短で1秒間隔で記録測定するように設定し、おんどとりWebStorageへ1分毎にデータを自動送信している場合に、毎分に近い間隔で最新の数分間の記録データを取得する運用をカバーできるように設計しました。
登録台数が60台を超えているような場合では1分ごとの確認とはなりませんが、APIで取得できるデータ件数を300件(1秒記録間隔であれば5分間の記録に相当)にしておりますので、APIを毎秒呼び出すことで「60台x5分間＝300台程度」の運用まではカバーできるように設計をしています。
レートリミット自体は短期間に一斉にアクセス集中することを避けて負荷を分散するための方針となります。ご了承ください。
| 項目名 | 値 |
|---|---|
| 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文字) | 必須 | --- | グラフデータを取り出す機器シリアル番号。複数台指定はできません。 |
| type | string( json/csv/csv2 ) | json | 受け取るグラフデータの形式。json形式とcsv形式を選択できます。(*1) |
(*1) type=csvを設定した場合、json_encodeされた値がCSV形式で返ります。type=csv2を設定することで、CSV形式のレスポンス例と同じ形式の値を返します。
リクエストヘッダ
POST /v1/devices/latest-data HTTP/1.1 Host: api.webstorage.jp:443 Content-Type: application/json X-HTTP-Method-Override: GET
リクエストボディ
{
"api-key":"73pfobnche8d1p6laqnemsbnpkght3bjv047oid6p2sg3",
"login-id":"tbzz9999",
"login-pass":"ppaasswwoorrdd",
"remote-serial":"52120001"
}
※この例では、TR-71wf[52120001]の現在値グラフデータ300件をjson形式で取得。
WindowsやMac端末などのコマンドラインから利用可能なcurlコマンドを使ったリクエスト例です。リクエストヘッダとリクエストボディを含む形でのコマンド例になっています。
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":"52120001"}' \
https://api.webstorage.jp:443/v1/devices/latest-data
| 項目名 | 値 | 説明 |
|---|---|---|
| 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
{
"error":{
"code": エラーコード,
"message": "エラーの内容"
}
}
下記の表において、channel.nameのように項目名にピリオド(.)が含まれるような場合は、channelに含まれる配列の要素を示しています。
| 項目名 | 型 | 説明 |
|---|---|---|
| serial | string | 指定した機器のシリアル番号 |
| model | string | 指定した機器のモデル名称 |
| name | string | 指定した機器の機器名称 |
| time_diff | string (*1) | 機器の時差情報[単位は分]。子機の場合は親機に設定されている時差情報。 |
| std_bias | string (*1) | 機器の標準時差[単位は分]。子機の場合は親機に設定されている標準時差。 |
| dst_flg | string (*1) | 夏時間フラグ。機器の夏時間設定がONの場合は1、OFFの場合（夏時間の設定がない機種はOFF）は0が返ります。 |
| dst_bias | string (*1) | 機器の夏時間時差[単位は分]。夏時間設定のON/OFFに関わらず60固定。 |
| channel | 配列 | 測定チャンネル情報。データが不足している機器を指定した場合には空配列となる場合があります。 |
| channel.name | string | チャンネル名称 |
| channel.num | string (*1) | チャンネル番号 (0 ~ ) |
| channel.unit | string | チャンネル測定単位 |
| data | 配列 | データ件数0件の場合には空配列となります。 |
| data.unixtime | string (*1) | グラフデータのunixtime |
| data.data-id | string (*1) | グラフデータのdata-id(*2) |
| data.ch1 | string(*1)(*3) | 上記unixtimeにおけるch1の値 |
| data.ch2 | string(*1)(*3) | 上記unixtimeにおけるch2の値。機器によりch2を測定していない場合には存在しません。 |
(*1) 値は数値ですが、型は文字型となっています。
(*2) data-idは0-65535までの連続するIDとなり、65535を超えると0に戻ります。この値とunixtimeを用いることでデータの連続性をチェックすることができます。現在値データを受信できていない期間がある場合は、その期間のdata-idが抜けている場合があります。ただし、TR41/TR42/TR45のモニタリングデータについては常に「"data-id": 0」となります。
(*3) 計測値が取得できた場合は文字型の数値が返りますが、エラーが発生している場合は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
{
"serial":"52140001",
"model":"TR-72wf",
"name":"東側の窓の外",
"time_diff": "540",
"std_bias": "0",
"dst_flg": "0",
"dst_bias": "60",
"channel":[
{
"name":"temp",
"num":"0",
"unit":"C"
},{
"name":"humid",
"num":"1",
"unit":"%"
}],
"data":[
{
"unixtime": "123456789",
"data-id": "123",
"ch1":"23.5",
"ch2":"65"
},{
"unixtime": "123456800",
"data-id": "124",
"ch1":"25.5",
"ch2":"68"
}, ... ,{
"unixtime": "123456999",
"data-id": "324",
"ch1":"21.5",
"ch2":"60"
}
]
}
CSV形式でデータを受け取る際のデータ形式についての説明です。
この形式はT&D GraphなどでデータをCSV出力する形式と同じです。
| 1行目 (ヘッダ行) | Date/Time (固定値) | Date/Time (固定値) | No.1 (固定値) | No.2 (固定値)(チャンネル数により増減) |
|---|---|---|---|---|
| 2行目 (ヘッダ行) | 時差:GMT**:**/夏時間:on/off (*1) (機器の時差設定) | 日付のシリアル値(Excel) (固定値) | ch1のチャンネル名称 | ch2のチャンネル名称 (チャンネル数により増減) |
| 3行目 (ヘッダ行) | (固定値で空データ) | (固定値で空データ) | ch1の測定単位 | ch2の測定単位 (チャンネル数により増減) |
| 4行目以降 (データ行) | 測定時刻 (*2) | 測定時刻のexcelのシリアル値 (*3) | ch1の測定値 | ch2の測定値 (チャンネル数により増減) |
(*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 "Date/Time","Date/Time","No.1" "時差:GMT+9:00/夏時間:off","日付のシリアル値(Excel)","Temp" "","","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" .....