Specifications for Metric APIs


APIs of the Metrics type provide the historical values of metrics, including the current day values of some metrics such as Production. Before registering the Metrics APIs as the data sources in Common Data Service, you need to standardize the APIs according to the following specifications.


HTTP Method


POST

Request Parameters


Name

Mandatory/Optional

Data Type

Description

orgId

Mandatory

String

The organization ID which the metric belongs to.

mdmIds

Mandatory

String

The object instance ID which the metric belongs to. Separate multiple IDs by commas. Format: mdmId1,mdmId2,mdmId3,mdmId4; format with aggregation groups: mdmId1,mdmId2:group1|mdmId3,mdmId4:group2.

metrics

Mandatory

String

The metric ID. Separate multiple IDs by commas.

timeGroup

Mandatory

String

The time granularity by which the metric is aggregated. The following granularity are supported: RAW (raw data), 1m (1 minute), 5m (5 minutes), 10m (10 minutes), 15m (15 minutes), 30m (30 minutes), 60m (60 minutes), H (hour), D (day), W (week), M (month), Y (year), T (total), L (Latest).

startTime

Optional if timeGroup is L, otherwise mandatory

String

The start time of the sampling data. Format: YYYY-MM-dd hh:mm:ss.

endTime

Optional if timeGroup is L, otherwise mandatory

String

The end time of the sampling data. Its format must be consistent with startTime.

dimensions

Optional

String

The dimension other than asset and time, such as device type and device manufacturer.

rollup

Optional

Boolean

Whether to roll up data for queries by multiple dimensions.

rollupDimensions

Optional

String

The rollup dimension for queries by multiple dimensions. If blank, the value of dimensions is used.

withDimensionName

Optional

Boolean

Whether to include the dimension name when returning a dimension ID for UI display. If true, the returned dimension name should be in this format: {dimensionId}Name, for example, API providers should return alertRuleName for the alertRule dimension.

locale

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

Optional

String

Filter the returned data based on the expression. 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

Optional

String

Sort the returned data based on the expression. 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

Optional

Integer

The number of the returned records on a single page.

pageNo

Optional

Integer

The number of page to be returned. The default value is 1.

virtualDimensions

Optional

String

A self-defined dimension to replace the dimensions parameter.

Response Parameters


Name

To Return Definitely/Conditionally

Data Type

Description

mdmId

Definitely

String

The instance that the metric belongs to.

time

Definitely

String

The data timestamp in local time format.

metric

Definitely

Object

The time-series value of the metric.

dimension

Conditionally

Object

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.

Request Content Type


application/x-www-form-urlencoded

Response Content Type


application/json; charset = UTF-8

Request Sample


POST {requestURL}?orgId=yourOrgId
Content-Type: application/x-www-form-urlencoded
Payload: mdmIds=yourMdmId&metrics=yourMetrics&startTime=yourStartTime&endTime=yourEndTime&timeGroup=yourTimeGroup

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