Dimension Value TopN and Monitoring Data Query Interface
Updated at：2025-11-03
API description
This API retrieves the TopN dimension values along with corresponding monitoring data for a specific metric under defined dimensions of a cloud product instance.
Request structure
- method：POST
- Request URL: /csm/api/v2/dimensions/top
Request parameters
| Name | Types | Description | Required or not | Parameter location |
|---|---|---|---|---|
| userId | String | User ID | Yes | Body |
| scope | String | Cloud product identifier. For values, please refer to [Cloud Product Identifier List](BCM/Cloud Product Monitor List/Cloud Product Monitor Object Type List.md) | Yes | Body |
| region | String | Region identifier. For values, please refer to [Region List](BCM/API Reference/Service domain.md) | Yes | Body |
| metricName | String | Monitor Metric name, limited to the following character set: "0~9, A~Z, a~z", "_" | Yes | Body |
| statistics | String | Statistic method type. Optional values: average, maximum, minimum, sum, sampleCount. | Yes | Body |
| dimensions | Map<String, String> | Instance dimensions and metric dimensions, instance dimensions: Instance ID or parent instance ID (required); metric dimensions: Dimensions carried by the monitoring metric (optional) | Yes | Body |
| labels | Set<String> | Metric dimensions to be sorted | Yes | Body |
| startTime | String | Monitor data start time, refer to [Date and Time](BCM/API Reference/General Description.md), in UTC format | Yes | Body |
| endTime | String | Monitor data end time, refer to [Date and Time](BCM/API Reference/General Description.md), expressed in UTC date | Yes | Body |
| order | String | Sorting method, optional values top (descending), bottom (ascending), default top | No | Body |
| topNum | int | Number of topNum items retained after sorting, default: 10, maximum: 1000 | No | Body |
| cycle | int | Statistical period, unit: second, default value: 60 | No | Body |
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 ID |
| userId | String | User ID |
| serviceName | String | Cloud product identifier |
| metricName | String | Metric name |
| resourceId | String | Instance ID |
| dimensions | List<Dimension> | Metric dimension |
| dataPoints | List<TsdbQueryDataPoint> | Monitor Metric data |
Dimension
| Name | Types | Description |
|---|---|---|
| name | String | Dimension name |
| value | String | Dimension value |
TsdbQueryDataPoint
| Name | Types | Description |
|---|---|---|
| timestamp | String | Time corresponding to the monitor data |
| average | Double | Average of Metrics within the statistical period |
| sum | Double | Sum of Metrics within the statistical period |
| maximum | Double | Maximum value of Metrics within the counting cycle |
| minimum | Double | Minimum value of Metrics within the statistical period |
| sampleCount | Integer | Number of DataPoints for the Metric within the statistical period |
Request example
JSON
1{
2 "userId": "453bf9********************9090dc",
3 "scope": "BCE_NAT",
4 "region": "bj",
5 "metricName": "ConnNumber",
6 "statistics": "average",
7 "startTime": "2024-07-08T11:30:53Z",
8 "endTime": "2024-07-08T11:32:53Z",
9 "dimensions": {
10 "NatId": "nat-be********cw"
11 },
12 "labels": [
13 "FixIp"
14 ],
15 "topNum": 2,
16 "order": "top",
17 "cycle": 60
18}Response example
JSON
1[
2 {
3 "requestId": "3adb033a103945c0921914c4c23d6ab8",
4 "userId": "453bf9********************9090dc",
5 "serviceName": "BCE_NAT",
6 "metricName": "ConnNumber",
7 "resourceId": "nat-be********cw",
8 "dimensions": [
9 {
10 "name": "FixIp",
11 "value": "100.2.107.13"
12 }
13 ],
14 "dataPoints": [
15 {
16 "timestamp": "2024-07-08T11:30:53Z",
17 "average": 335.0
18 },
19 {
20 "timestamp": "2024-07-08T11:31:53Z",
21 "average": 367.0
22 },
23 {
24 "timestamp": "2024-07-08T11:32:53Z",
25 "average": 456.0
26 }
27 ]
28 },
29 {
30 "requestId": "3adb033a103945c0921914c4c23d6ab8",
31 "userId": "453bf9********************9090dc",
32 "serviceName": "BCE_NAT",
33 "metricName": "ConnNumber",
34 "resourceId": "nat-be********cw",
35 "dimensions": [
36 {
37 "name": "FixIp",
38 "value": "100.2.107.14"
39 }
40 ],
41 "dataPoints": [
42 {
43 "timestamp": "2024-07-08T11:30:53Z",
44 "average": 153.0
45 },
46 {
47 "timestamp": "2024-07-08T11:31:53Z",
48 "average": 148.0
49 },
50 {
51 "timestamp": "2024-07-08T11:32:53Z",
52 "average": 142.0
53 }
54 ]
55 }
56]