数据流 API

@cz 最后修改于 2020-07-13 10:43:08 rev.5230 - 最近修改

数据流 API

概述

本文主要描述了如何对数据流进行管理和查询.

数据流是指设备主动上报的某种类型的数据点的集合, 比如室内温度.

版本

V2.1

作者

@author ChengZhen

修改历史

2018/10/12

添加 MQTT 和 CoAP API 接口定义

2018/9/28

添加错误消息码定义
添加示例等更详细的描述

REST API 接口

服务器地址:

http://{domain-name}/v2/stream/

所有 API 接口必须以此地址为基本地址

查询数据点列表

GET /stream/list

请求参数

NAME	REQ	TYPE	DEFAULT	DESCRIPTION
offset	-	Number	0	开始返回的记录的索引 (用于分页查询)
limit	-	Number	100	最多返回的记录数，最大不能设置超过 10000
order	-	String	asc	排序方式 (`asc`, `desc`)
orderBy	-	String	time	排序字段名, 目前只支持 `time` 字段排序
did	true	String	-	设备 ID , 如果没有指定则为设备的 MAC 地址
name	true	String	-	数据流名称, 如果没有指定则为产品的编码 (Key)
field	-	String	value	数据字段名称, 产品属性名, 多个名称以 `,` 分隔
tid	-	String	-	标签 ID (MAC)
start	-	Number	-	开始时间, UINX 时间戳, 单位为毫秒
end	-	Number	now	结束时间, UINX 时间戳, 单位为毫秒
duration	-	String	1h	查询时长.

查询时长 duration 支持的单位有:

TYPE	NOTE
w	周
d	天
h	小时
m	分钟
s	秒

时间段条件规则:

duration 必须大于 0
当 start 和 end 都存在时， duration 将被忽略
end 不能小于等于 start

响应结果:

返回数据流中符合查询条件的数据点的列表.

{
    "did": String,      // 设备 ID (ObjectId)
    "name": String,     // 数据流名称
    "start": Number,    // 开始时间
    "end": Number,      // 结束时间
    "data": {           // 数据内容
        "columns": [String],    // 数据点列表列名， 和数据点中的值一一对应
        "values": [[Any]]       // 数据点的值， 和列名列表中的名称一一对应
    }
}

data.columns 包含了返回的数据点的所有属性的名称，它们的顺序和每个数据点中的值的顺序是一一对应的
data.values 数组中的每一项表示一个数据点，它由多个数值组成的数组

示例 (温度数据流)

请求

GET /stream/list?did=59a373913033836125e68907&name=humiture&field=temperature

应答

{
    "did": "59a373913033836125e68907",
    "name": "humiture",
    "field": "temperature",
    "start": 1538137806794,
    "end": 1538141406794,
    "data": {
        "columns": ["at", "temperature"], // 第 1 列为时间戳， 第 2 列为温度值
        "values": [
            [1538141031055, 25.5], // 第 1 个数据点, 时间戳为 1538141031055, 温度值为 25.5
            [1538141033702, 25.6], // 第 2 个数据点
            [1538141037463, 25.7], // 第 3 个数据点
        ]
    }
}

错误信息:

CODE	MESSAGE	NOTE
100401	Unauthorized	用户没有登录, 或身份没有认证
100403	Permission denied	禁止访问, 没有相应的权限
104001	Miss required parameter	缺失必选参数，请参考API文档
100107	Invalid time range	无效的时间段
100108	Invalid device ID	无效的设备 ID
100109	Invalid data stream name	无效的数据流名称

数据流统计

GET /stream/stat

请求参数

NAME	REQ	TYPE	DEFAULT	DESCRIPTION
did	true	String	-	设备 ID, 如果没有指定则为设备的 MAC 地址
name	true	String	-	数据流名称, 如果没有指定则为产品的编码 (Key)
field	-	String	value	数据字段名称, 产品属性名, 多个名称以 `,`分隔
fields	-	String	-	多个名称以 `,`分隔
tid	-	String	-	标签 ID (MAC)
interval	-	String	1m	统计时间分组 (包含时间单位)
method	-	String	avg	统计方法 (聚合函数), 多个方法以 `,`分隔
fill	-	String	null	空记录填充模式
start	-	Number	-	开始时间, UINX 时间戳, 单位为毫秒
end	-	Number	now	结束时间, UINX 时间戳, 单位为毫秒
duration	-	String	1h	查询时间长度 (包含时间单位)

field 字段名

要查询的字段名，即事物的属性名

duration 时间段

时间段条件规则和 /stream/list 类似

只统计指定时间段以内的数据点
结束时间, 如果未指定则为服务器当前时间
开始时间, 如果未指定则为结束时间减去 duration
查询时长, 如 1d, 1h, 1m 等等, 只有当未同时指定 start 和 end 时通过这个值得到相应的 end 和 start.

建议的值有 (duration - interval):

5m - 10s
15m - 10s
1h - 10s
6h - 1m
12h - 1m
24h - 5m
2d - 5m
7d - 30m
30d - 1h

interval 聚合间隔

统计时将对每个时间段内的数据进行聚合计算, 聚合为一个数据点, 以降低数据采样率, 以免返回数据过长

支持的统计分组间隔时间单位有: s, m, h, d

建议的值有:

10s
1m
5m
10m
30m
1h
6h
1d
7d

method 聚合方法

统计时对每个时间分组内的数据进行聚合计算的方法

支持的聚合方法有:

Method	Type	Note
avg/mean	聚合函数	平均值
median	聚合函数	中间值
count	聚合函数	数量
min	选择函数	最小值
max	选择函数	最大值
sum	聚合函数	总数
first	选择函数	第一个值
last	选择函数	最后一个值
spread	聚合函数	极差，最大值和最小值的差值
mode	聚合函数	最频繁值
stddev	聚合函数	标准差
integral	聚合函数	积分

fill 聚合空记录填充模式

当某个时间段内没有任何数据时的填充方法

支持的空记录填充模式有:

Method	Note
previous	填充先前时间段的值
linear	线性插值的方式填充
null	填充 `null` 值
none	不填充, 即在结果集中不包含这个时间段
number	填充一个指定的数字, 默认填充 `0`

响应结果:

{
    "did": String,          // 设备 ID (ObjectId)
    "name": String,         // 数据流名称
    "start": Number,        // 开始时间
    "end": Number,          // 结束时间
    "method": String,       // 聚合方法
    "fill": String,         // 填充模式
    "interval": String,     // 聚合周期
    "data": {               // 统计数据点, 格式和 /stream/list 响应结果类似
        "columns": [String],
        "values": [[Any]]
    }
}

示例 (温度数据流)

请求

GET /stream/list?did=59a373913033836125e68907&name=humiture&field=temperature&method=min&interval=1m

应答

{
    "did": "59a373913033836125e68907",
    "name": "humiture",
    "field": "temperature",
    "start": 1538137806794,
    "end": 1538141406794,
    "method": "min",
    "interval": "1m",
    "data": {
        "columns": ["at", "temperature"], // 第 1 列为时间戳， 第 2 列为温度值
        "values": [
            [1538141031000, 25.5], // 第 1 个时间段统计数据点, 开始时间为 1538141031000, 最小温度值为 25.5, 最大温度值为 25.7
            [1538141033000, 25.1], // 第 2 个时间段统计数据点
            [1538141037000, 25.0], // 第 3 个时间段统计数据点
        ]
    }
}

错误信息:

CODE	MESSAGE	NOTE
100401	Unauthorized	用户没有登录, 或身份没有认证
100403	Permission denied	禁止访问, 没有相应的权限
104001	Miss required parameter	缺失必选参数，请参考API文档
100107	Invalid time range	无效的时间段
100108	Invalid device ID	无效的设备 ID
100109	Invalid data stream name	无效的数据流名称
100110	Invalid method name	无效的聚合模式, 如离散数据只支持 count 等操作
100111	Invalid interval	无效的聚合周期

查询历史属性值

GET /stream/get

查询指定的设备，指定时间的属性值

请求参数

NAME	REQ	TYPE	DEFAULT	DESCRIPTION
did	true	String	-	设备 ID, 如果没有指定则为设备的 MAC 地址
name	true	String	-	数据流名称, 如果没有指定则为产品的编码 (Key)
field	-	String	value	数据字段名称, 产品属性名, 多个名称以 `,`分隔
fields	-	String	-	多个名称以 `,`分隔
tid	-	String	-	标签 ID (MAC)
start	-	Number	-	开始时间, UINX 时间戳, 单位为毫秒
end	-	Number	now	结束时间, UINX 时间戳, 单位为毫秒
duration	-	String	1h	查询时间长度 (包含时间单位)

响应结果:

{
    "did": String,          // 设备 ID (ObjectId)
    "name": String,         // 数据流名称
    "start": Number,        // 开始时间
    "end": Number,          // 结束时间
    "data": {               // 统计数据点
        "foo": Number
    }
}