Query Historical Metric¶
Get the historical data of metrics by metric IDs. The returned data can be grouped by object types or aggregated by dimensions.
Request Format¶
GET/POST https://{api-gateway}/cds-metric-service/v1.0/metric?action=query
Request Parameters¶
Name |
Location |
Mandatory/Optional |
Data Type |
Description |
---|---|---|---|---|
orgId |
Query |
Mandatory |
String |
The organization ID which the metric belongs to. How to get orgId >> |
mdmIds |
Query/Form |
Mandatory |
String |
The object instance ID which the metric belongs to. Separate multiple IDs by commas. Up to 20000 object instances are allowed in a single query. To ensure query performance, it is recommended that you pass in no more than 100 object instances in a single query. Format: mdmId1,mdmId2,mdmId3,mdmId4; format with aggregation groups: mdmId1,mdmId2:group1|mdmId3,mdmId4:group2. |
metrics |
Query/Form |
Mandatory |
String |
The metric ID. Separate multiple IDs by commas. Up to 100 metrics are allowed in a single query. How to get metrics>> |
startTime |
Query/Form |
Mandatory |
String |
The start time of the sampling data. Format: yyyy-MM-dd HH:mm:ss. Common Data Service queries the data by the local time of where each asset is located. |
endTime |
Query/Form |
Mandatory |
String |
The end time of the sampling data. Its format must be consistent with “startTime”. Make sure the number of days between “startTime” and “endTime” is not greater than 4000. |
timeGroup |
Query/Form |
Mandatory |
String |
The time granularity by which the metric is aggregated. The following granularity are supported: 1m (1 minute), 5m (5 minutes), 10m (10 minutes), 15m (15 minutes), 30m (30 minutes), H (hour), D (day), W (week), M (month), Y (year), T (total). Make sure the calculated value of this formula is not greater than 400: (endTime-startTime) / timeGroup, that is the number of the designated time granularity between “startTime” and “endTime” is not greater than 400. |
preserveIndex |
Query/Form |
Optional |
Boolean |
Whether to preserve the index (non-metric data such as mdmId and time). The default value is false. |
dimensions |
Query/Form |
Optional |
String |
The dimension other than asset and time, such as device type and device manufacturer. This parameter is used to aggregate or filter the returned data. Separate multiple dimensions by commas. Up to 10 dimensions are allowed in a single query. How to get dimensions>> |
rollup |
Query/Form |
Optional |
Boolean |
Whether to roll up data for queries by multiple dimensions. |
rollupDimensions |
Query/Form |
Optional |
String |
The rollup dimension for queries by multiple dimensions. |
withDimensionName |
Query/Form |
Optional |
Boolean |
Whether to include the dimension name when returning a dimension ID. |
locale |
Query/Form |
Optional |
String |
Use zh-CN, en-US, ja-JP, or es-ES. If not specified, the value is set to en_US by default. |
filter |
Query/Form |
Optional |
String |
Specify how to filter the returned data by metrics or dimensions. For example, [[{“field”:”field1”,”operator”:”>=”,”value”:”1”},{“field”:”field2”,”operator”:”<=”,”value”:”2”}],[{“field”:”field3”,”operator”:”==”,”value”:”3”}]], which means the returned data is filtered by (field1 >= 1 and field2 <= 2) or (field3=3). |
orderBy |
Query/Form |
Optional |
String |
Specify how to sort the returned data by metrics or dimensions. For example, [{“field”:”field1”,”order”:”ASC”}, {“field”:”field2”,”order”:”DESC”}], which means the returned data is sorted first by field1 in ascending order and then by field2 in descending order. |
pageSize |
Query/Form |
Optional |
Integer |
The number of the returned records on a single page. The maximum number is 20000. |
pageNo |
Query/Form |
Optional |
Integer |
The number of page to be returned. |
mdmTypes |
Query/Form |
Optional |
String |
The object type ID which the metric belongs to. This parameter is used to filter the object instances to be queried. |
virtualDimensions |
Query/Form |
Optional |
String |
Specify a self-defined dimension to replace the “dimensions” parameter. Format: mdmId,dim1,dim2|mdmId1,enum1A,enum2A|mdmId2,enum1B,enum2B. |
Response Content Type¶
application/json; charset = UTF-8
Response Codes¶
Samples¶
Request Sample¶
GET https://{api-gateway}/cds-metric-service/v1.0/metric?action=query&orgId=yourOrgId&mdmIds=yourMdmId&metrics=yourMetrics&startTime=yourStartTime&endTime=yourEndTime&timeGroup=yourTimeGroup&pageNo=1&pageSize=20000
Response Sample¶
{
"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",
"traceId": "1234567890abcdefghijkl0987654321"
}