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