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 specified range: (endTime-startTime) / timeGroup, that is the number of the designated time granularity between “startTime” and “endTime” is not greater than specified range. The specified range of 1m/5m/10m/15m/30m is 2880, the specified range of H is 8784, and the specified range of D/W/M/Y is 576.
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, starting from 1.
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 Parameters¶

Name	To Return Definitely/Conditionally	Data Type	Description
mdmId	Definitely	String	The object instance that the metric belongs to. To ensure query performance, it is recommended that you pass in no more than 100 object instances in a single query.
time	Definitely	String	The data timestamp in local time format.
metric	Definitely	Object	Describe the time-series values of the metric.
dimension	Conditionally	Object	Describe the dimension information of the metric.
pagination	Definitely	Pagination Struct	Describe the pagination information. See Pagination Struct.

Pagination Struct ¶

Name	To Return Definitely/Conditionally	Data Type	Description
pageNo	Definitely	Integer	The number of page to be returned, starting from 1.
pageSize	Definitely	Integer	The number of the returned records on a single page.
totalSize	Definitely	Integer	The total number of the returned records.

Response Codes¶

See Common Data Service API 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"
}