Query Data Interface
Interface Description
The time series data of one or more statistical data of designated indexes are acquired. The cloud product monitoring data, the site monitoring data or the custom monitoring data pushed by you can be acquired.
Interface Restriction
The number of data points returned at one time cannot exceed 1,440.
Request Structure
- Request method: GET
- Request URL: /json-api/v1/metricdata/{userid}/{scope}/{metricName}?{Query parameter}
- Query parameter: dimensions={dimensions}&statistics[]={statistics1, statistics2, statistics3...}&periodInSecond={periodInSecond}&startTime={startTime}&endTime={endTime}
Request Parameter
| Name | Type | Description | Required or not | Parameter position |
|---|---|---|---|---|
| userId | String | Tenant ID | Yes | URL parameter |
| scope | String, only limited to usage of the following character sets: "0~9, "A~Z", "a~z" and "_". | Name space | Yes | URL parameter |
| metricName | String, only limited to usage of the following character sets: "0~9, "A~Z", "a~z" and "_". | Monitoring index name | Yes | URL parameter |
| statistics[] | Statistics, the optional values are average, maximum, minimum, sum, samplecount according to statistics1, statistics2 and statistics3 formats. | Type of statistical method | Yes | Query parameter |
| dimensions | String, composed of dimensionName:dimensionValue. The monitoring items are connected by semicolons when they have multiple dimensions, e.g. dimensionName: dimensionValue; dimensionName: dimensionValue. One dimension value can be designated only for the same dimension. | Dimension list | Yes | Query parameter |
| startTime | For DateTime, please refer to date and time, and it is represented by UTC date. | Start time of query | Yes | Query parameter |
| endTime | For DateTime, please refer to date and time, and it is represented by UTC date. | End time of query | Yes | Query parameter |
| periodInSecond | Integer, multiple of 60, unit: Seconds (s) | Statistical period | Yes | Query parameter |
Parameter Interpretation
- For the concepts of name space scope, monitoring item metric, statistical method Statistic, Dimension, etc., please refer to Core Concepts.
Response Parameter
| Name | Type | Description |
|---|---|---|
| requestId | String | Request identification |
| code | String | Return code |
| message | String | Error message |
| dataPoints | List (DataPoint) | Monitoring index |
DataPoint
| Name | Type | Description |
|---|---|---|
| average | double | Average value of monitoring items in the statistical period |
| sum | double | Sum value of monitoring items in the statistical period |
| minimum | double | Minimum value of monitoring items in the statistical period |
| maximum | double | Maximum value of monitoring items in the statistical period |
| sampleCount | Integer | Data points of monitoring items in the statistical period |
| timestamp | For DateTime, please refer to Date and Time, and it is represented by UTC date. | Time corresponding to the statistical period of monitoring items |
Request Example
In order to display more clearly, the request example is wrapped. The URL path and Query parameter are in the same row at the actual structure request.
GET /json-api/v1/metricdata/fakeuser1ba678asdf8as7df6a5sdf67/BCE_BCC/CpuIdlePercent?
dimensions=InstanceId:fakeid-2222-8888-1111-13a8469b1fb2
&statistics[]=average,maximum,minimum
&periodInSecond=60
&startTime=2019-04-16T13:55:01Z
&endTime=2019-04-16T14:00:01Z
HTTP/1.1
Host:bcm.bj.baidubce.com:80 Response Example
Successful Response Example
In querying the data, you should fill in the statistics[]parameter. The value of this parameter decides the attributes in one dataPoint in the response.
When statistics[]=average, the examples of return results are as follows:
HTTP/1.1 200 OK
x-bce-request-id: dwegvad4-dwea-4d3dsa-8ew2-4b7263fs1ecd
Content-Type: application/json;charset=UTF-8
{
"requestId": "17f101a7-67a8-4c2e-93d7-60c0d4a21f0c",
"code": "OK",
"message": "OK",
"dataPoints": [
{
"average": 2.24,
"timestamp": "2019-04-16T13:55:01Z"
},
{
"average": 0.22,
"timestamp": "2019-04-16T13:56:01Z"
},
{
"average": 0.19,
"timestamp": "2019-04-16T13:57:01Z"
},
{
"average": 0.18,
"timestamp": "2019-04-16T13:58:01Z"
},
{
"timestamp": "2019-04-16T13:59:01Z"
}
]
} When statistics[]= average, sum and minimum, the examples of return results are as follows:
HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
{
"requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
"code": "OK",
"message": "OK",
"successList": [
{
"dataPoints": [
{
"average": 40359.0,
"sum": 80718.0,
""minimum":39900.0,
"timestamp": "2019-04-23T00: 00: 00Z"
}
]
}
]
} Failed Response Example
When your request structure is correct, but the corresponding monitoring data are not found or the input parameter is incorrect, BCM returns return codes of 200 OK to you, and display the specific error reasons in the return body.
Case I: the data are not queried. For the user, name space, monitoring item and dimension designated in the request, no monitoring data are queried within the period from the start time to the end time.
When this case appears, the corresponding time points are returned to you, but there are no monitoring data.
HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
{
"requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
"code": "OK",
"message": "OK",
"successList": [
{
"dataPoints": [
{
"timestamp": "2019-04-23T00: 00: 00Z"
}
]
}
]
} Case II: the parameter is incorrect. The endTime parameter lacks in the following example.
HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
{
"requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
"code": "INVALID_PARAMETER",
"message": "Required endTime parameter String is not present"
} The format of the median of the dimension parameter is incorrect in the following example.
HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
{
"requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
"code": "INVALID_PARAMETER_VALUE",
"message": "Wrong dimensions format, example: name:value;name:value"
}