指标接口规范¶
指标
类型的接口提供指标的历史数值,包括部分指标的当日数值,例如发电量。将 指标
类型的接口注册为数据源之前,需按照以下规范对接口进行标准化。
请求参数¶
名称 | 必需/可选 | 数据类型 | 描述 |
---|---|---|---|
orgId | 必需 | String | 指标所属的组织 ID。 |
mdmIds | 必需 | String | 指标对应的对象实例的标识符,多个对象实例之间用英文逗号隔开。基础查询格式:mdmId1,mdmId2,mdmId3,mdmId4;分组聚合查询格式:mdmId1,mdmId2:group1|mdmId3,mdmId4:group2。 |
metrics | 必需 | String | 指标的标识符,多个指标之间用英文逗号隔开。 |
timeGroup | 必需 | String | 指标聚合的时间粒度。支持以下时间粒度:RAW (原始数据),1m(1分钟),5m(5分钟),10m(10分钟),15m(15分钟),30m(30分钟),60m(60分钟),H(小时),D(日),W(周),M(月),Y(年), T(总计), L(最新数据)。 |
startTime | timeGroup 为 L 时可选,为其他时间粒度时必需 | String | 采样数据开始时间,格式:YYYY-MM-dd hh:mm:ss。 |
endTime | timeGroup 为 L 时可选,为其他时间粒度时必需 | String | 采样数据结束时间,格式与开始时间保持一致。 |
dimensions | 可选 | String | 除资产和时间之外的维度,例如:设备型号、设备制造商。 |
rollup | 可选 | Boolean | 多维度查询时是否进行分级小计。 |
rollupDimensions | 可选 | String | 多维度查询时需要进行聚合的维度。若置空,则使用 dimensions 的值。 |
withDimensionName | 可选 | Boolean | 在返回维度标识符时,是否同时返回维度名称,用于 UI 展示。当指定为 true 时,返回的维度名称的命名规则为 {dimensionId}Name,例如对于 alertRule 维度,数据源提供方需在响应结果中提供 alertRuleName 字段。 |
locale | 可选 | String | 中文:zh-CN, 英文:en-US, 日语:ja-JP,西班牙语:es-ES。默认为 en-US。 |
filter | 可选 | String | 返回结果按表达式进行过滤。例如:[[{“field”:”field1”,”operator”:”>=”,”value”:”1”},{“field”:”field2”,”operator”:”<=”,”value”:”2”}],[{“field”:”field3”,”operator”:”==”,”value”:”3”}]],该表达式含义为:(field1 >= 1 and field2 <= 2) or (field3=3)。 |
orderBy | 可选 | String | 返回结果按表达式进行排序。例如:[{“field”:”field1”,”order”:”ASC”}, {“field”:”field2”,”order”:”DESC”}],该表达式含义为:按 field1 升序进行一级排序,并按 field2 降序进行二级排序。 |
pageSize | 可选 | Integer | 分页查询时单页返回记录的条数。 |
pageNo | 可选 | Integer | 分页查询时指定页码,默认值为 1。 |
virtualDimensions | 可选 | String | 指定自定义的维度信息替代 dimensions。 |
响应参数¶
名称 | 必然/可能返回 | 数据类型 | 描述 |
---|---|---|---|
mdmId | 必然返回 | String | 指标所属的对象实例的标识符。 |
time | 必然返回 | String | 数据本地时间标记。 |
metric | 必然返回 | Object | 指标的时序数据值。 |
dimension | 可能返回 | Object | 指标的维度信息。 |
pagination | 必然返回 | Pagination 结构体 | 描述分页信息。参见 Pagination 结构体。 |
Pagination 结构体 ¶
名称 | 必然/可能返回 | 数据类型 | 描述 |
---|---|---|---|
pageNo | 必然返回 | Integer | 请求页数,从 1 开始。 |
pageSize | 必然返回 | Integer | 每页的记录数。 |
totalSize | 必然返回 | Integer | 记录总数。 |
请求示例¶
POST {requestURL}?orgId=yourOrgId
Content-Type: application/x-www-form-urlencoded
Payload: mdmIds=yourMdmId&metrics=yourMetrics&startTime=yourStartTime&endTime=yourEndTime&timeGroup=yourTimeGroup
返回示例¶
{
"pagination":
{
"pageNo": 1,
"pageSize": 20000,
"totalSize": 2
},
"data": [
{
"metrica": 9999.000000,
"metricb": 0.3717,
"metricc": 223,
"dimension1": "dimension1",
"dimension2": "dimension2",
"mdmId": "yourMdmId",
"time": "2019-01"
},
{
"metrica": 9999.000000,
"metricb": 0.0417,
"metricc": 25,
"dimension1": "dimension1",
"dimension2": "dimension2",
"mdmId": "yourMdmId",
"time": "2019-02"
}
],
"code": 0,
"msg": "OK"
}