Query Data API
API description
Retrieve Time Series data for one or more statistics based on specified Metrics, including Cloud Product Monitor data, Site Monitor data, or Custom Monitor data that you have uploaded.
API restriction
The number of DataPoints returned in a single response cannot exceed 1,440.
Request structure
- Method: GET
- URL: /json-api/v1/metricdata/{userid}/{scope}/{metricName}?{Query}
- Query: dimensions={dimensions}&statistics[]={statistics1,statistics2,statistics3...}&periodInSecond={periodInSecond}&startTime={startTime}&endTime={endTime}
Request parameters
| Name | Types | Description | Required or not | Parameter location |
|---|---|---|---|---|
| userId | String | Tenant ID | Yes | URL parameter |
| scope | String, limited to the following character set: 0~9, A~Z, a~z, _ | Scope | Yes | URL parameter |
| metricName | String, limited to the following character set: 0~9, A~Z, a~z, _ | Monitor Metric name | Yes | URL parameter |
| statistics[] | Statistics, in statistics1, statistics2, statistics3 format, options: average, maximum, minimum, sum, sampleCount | Statistic Method Type | Yes | Query |
| dimensions | A string formatted as dimensionName:dimensionValue. For Metrics with multiple Dimensions, connect them using semicolons, e.g., dimensionName:dimensionValue;dimensionName:dimensionValue. Each dimension can have only one specified value. | Dimension list | Yes | Query |
| startTime | DateTime, refer to Date and Time, expressed in UTC date | Query start time | Yes | Query |
| endTime | DateTime, refer to Date and Time, expressed in UTC date | Query end time | Yes | Query |
| periodInSecond | Integer, multiple of 60, unit: second (s) | Statistical Period | Yes | Query |
Parameter explanation
- For concepts like Scope, Metric, Statistic, and Dimension, refer to [Core Concepts](BCM/Product Description/Core concepts.md).
Response parameters
| Name | Types | Description |
|---|---|---|
| requestId | String | Request identifier |
| code | String | Return code |
| message | String | Error message |
| dataPoints | List（DataPoint） | Monitor Metric |
DataPoint
| Name | Types | Description |
|---|---|---|
| average | double | Average of Metrics within the statistical period |
| sum | double | Sum of Metrics within the statistical period |
| minimum | double | Minimum value of Metrics within the statistical period |
| maximum | double | Maximum value of Metrics within the counting cycle |
| sampleCount | Integer | Number of DataPoints for the Metric within the statistical period |
| timestamp | DateTime, refer to [Date and Time](BCM/API Reference/General Description.md#Date and time regulations), expressed in UTC date | Time corresponding to the statistical period of Metric |
Request example
For clarity, the request example has been line-wrapped. In actual request construction, the URL path and query parameters should be written on a single line.
1GET /json-api/v1/metricdata/fakeuser1ba678asdf8as7df6a5sdf67/BCE_BCC/CpuIdlePercent?
2dimensions=InstanceId:fakeid-2222-8888-1111-13a8469b1fb2
3&statistics[]=average,maximum,minimum
4&periodInSecond=60
5&startTime=2019-04-16T13:55:01Z
6&endTime=2019-04-16T14:00:01Z
7HTTP/1.1
8Host:bcm.bj.baidubce.com:80 Response example
Successful response example
When querying data, include the statistics\[] parameter, which determines the attributes for each dataPoint in the response.
When statistics[]=average, the response result example is as follows:
1HTTP/1.1 200 OK
2x-bce-request-id: dwegvad4-dwea-4d3dsa-8ew2-4b7263fs1ecd
3Content-Type: application/json;charset=UTF-8
4{
5 "requestId": "17f101a7-67a8-4c2e-93d7-60c0d4a21f0c",
6 "code": "OK",
7 "message": "OK",
8 "dataPoints": [
9 {
10 "average": 2.24,
11 "timestamp": "2019-04-16T13:55:01Z"
12 },
13 {
14 "average": 0.22,
15 "timestamp": "2019-04-16T13:56:01Z"
16 },
17 {
18 "average": 0.19,
19 "timestamp": "2019-04-16T13:57:01Z"
20 },
21 {
22 "average": 0.18,
23 "timestamp": "2019-04-16T13:58:01Z"
24 },
25 {
26 "timestamp": "2019-04-16T13:59:01Z"
27 }
28 ]
29}When statistics[]=average, sum, minimum, the response result example is as follows:
1HTTP/1.1 200 OK
2x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
3Content-Type: application/json;charset=UTF-8
4{
5 "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
6 "code": "OK",
7 "message": "OK",
8 "successList": [
9 {
10 "dataPoints": [
11 {
12 "average": 40359.0,
13 "sum": 80718.0,
14 ""minimum":39900.0,
15 "timestamp": "2019-04-23T00: 00: 00Z"
16 }
17 ]
18 }
19 ]
20}Unsuccessful response example
If your request is correctly structured but no corresponding monitoring data is found, or the input parameters are incorrect, BCM will return a 200 OK response code and provide details about the error in the response body.
Case 1: No data found. No monitoring data exists under the specified user, Scope, Metric, and Dimension for the given time period.
When this occurs, the corresponding time point will be returned, but without monitor data
1HTTP/1.1 200 OK
2x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
3Content-Type: application/json;charset=UTF-8
4{
5 "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
6 "code": "OK",
7 "message": "OK",
8 "successList": [
9 {
10 "dataPoints": [
11 {
12 "timestamp": "2019-04-23T00: 00: 00Z"
13 }
14 ]
15 }
16 ]
17}Case 2: Incorrect parameters. The following example is missing the endTime parameter.
1HTTP/1.1 200 OK
2x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
3Content-Type: application/json;charset=UTF-8
4{
5 "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
6 "code": "INVALID_PARAMETER",
7 "message": "Required endTime parameter String is not present"
8}The example below demonstrates an incorrect format for Dimension parameter values.
1HTTP/1.1 200 OK
2x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
3Content-Type: application/json;charset=UTF-8
4{
5 "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
6 "code": "INVALID_PARAMETER_VALUE",
7 "message": "Wrong dimensions format, example: name:value;name:value"
8}