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


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"
}