# 批量查询监控数据 - BatchListMetricData #### 功能介绍 批量查询指定时间范围内指定指标的指定粒度的监控数据，目前最多支持500指标的批量查询。 对于不同的period取值和查询的指标数量，默认的最大查询区间(to-from)不同。 规则为"指标数量\*(to-from)/监控周期\<=3000"，若超出阈值，会自动调整from以满足规则。 #### 接口约束 须知： 1. 单次POST请求消息体大小不能超过512KB，否则请求会被服务端拒绝。 2. 单个API的调用次数限制为500次/分钟，如果返回信息中包含ces.0429或Too Many Requests，则说明该API被限流。处理方法请参见[API调用流控处理建议](https://support.huaweicloud.com/api-ces/ces_03_0162.html)。 3. 对于不同的period取值和查询的指标数量，其对应的默认最大查询区间(to - from)也不同，计算规则为"指标数量 \* (to - from) / 监控周期 ≤ 3000"。 指标数量：请求参数metrics属性对应元素的个数。 监控周期：请求参数period属性对应的值，需要转为毫秒值。 3000：响应体中的所有datapoints（指标数据列表）总和。 - 当period值为"1"时，监控周期为60\*1000ms=60000ms。 - 当period值为"300" 时，监控周期为300\*1000ms=300000ms。 - 当period值为"1200" 时，监控周期为1200\*1000ms=1200000ms。 - 当period值为"3600" 时，监控周期为3600\*1000ms=3600000ms。 - 当period值为"14400" 时，监控周期为14400\*1000ms=14400000ms。 - 当period值为"86400" 时，监控周期为86400\*1000ms=86400000ms。 例如批量查询300个指标，监控周期为60000ms，可算出(to - from)最大值为"600000"，若设定的请求参数使(to - from)超出最大值，from值会自动调整为"to-600000"。 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/CES/doc?api=BatchListMetricData&version=v1)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-ces/ces_03_0045.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | ces:metricData:list | List | - | - | - | - | #### URI POST /V1.0/{project_id}/batch-query-metric-data 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释**: 项目ID。用于明确项目归属，配置后可通过该ID查询项目下资产，可以通过调用API获取，也可以从控制台获取。获取方式请参见[获取项目ID](https://support.huaweicloud.com/api-ces/ces_03_0057.html)。 **约束限制**: 不涉及。 **取值范围**: 长度为\[1,64\]个字符。 **默认取值**: 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Content-Type | 否 | String | **参数解释**: 发送的实体的MIME类型。 **约束限制**: 不涉及。 **取值范围**: 长度为\[1,64\]个字符。 **默认取值**: 默认使用 application/json; charset=UTF-8，如果API是对象、镜像上传等接口，媒体类型可按照流类型的不同进行确定。 | | X-Auth-Token | 否 | String | **参数解释**: 用户Token。 **约束限制**: 不涉及。 **取值范围**: 长度为\[1,16384\]个字符。 **默认取值**: 不涉及。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | metrics | 是 | Array of [MetricInfo] objects | **参数解释** 指标数据 **约束限制** 包含的指标数据对象个数为\[1,500\] | | period | 是 | String | **参数解释** 监控数据的聚合粒度，聚合解释可查看："[聚合含义](https://support.huaweicloud.com/ces_faq/ces_faq_0009.html)"。 - 1 监控资源的实时数据 - 60 聚合1分钟粒度数据，表示1分钟一个数据点 - 300 聚合5分钟粒度数据，表示5分钟一个数据点 - 1200 聚合20分钟粒度数据，表示20分钟一个数据点 - 3600 聚合1小时粒度数据，表示1小时一个数据点 - 14400 聚合4小时粒度数据，表示4小时一个数据点 - 86400 聚合1天粒度数据，表示1天一个数据点 **默认取值** 不涉及 **约束限制** 不涉及 **取值范围** 枚举值： | | filter | 是 | String | **参数解释**： 数据聚合的方式。 **约束限制**： period为1（原始值）时，filter字段不生效，参数值默认为average。period大于1时filter才起作用。 **取值范围**： 支持 average、variance、min、max、sum。 - average： 平均值 - variance：方差 - min：最小值 - max：最大值 - sum：求和 **默认取值**： 不涉及。 | | from | 是 | Integer | **参数解释** 查询数据起始时间，UNIX时间戳，单位毫秒 **约束限制** 当period为1时，若(to- from) \>4*3600* 1000，则from调整为 to - 4*3600*1000 当period为300时，若(to - from) \>24*3600* 1000，则from调整为 to - 24*3600*1000 当period为1200时，若(to - from) \>3*24* 3600*1000，则from调整为 to - 3* 24*3600*1000 当period为3600时，若(to -from) \> 10*24* 3600*1000，则from调整为 to -10* 24*3600*1000 当period为14400时，若(to - from) \>30*24* 3600*1000，则from调整为 to - 30* 24*3600*1000 当period为86400时，若(to -from) \> 180*24* 3600*1000，则from调整为 to - 180* 24*3600*1000 **取值范围** 毫秒级时间戳范围为\[1111111111111,9999999999999\] **默认取值** 不涉及 | | to | 是 | Integer | **参数解释** 查询数据截止时间，UNIX时间戳，单位毫秒 **约束限制** from 必须小于to **取值范围** 毫秒级时间戳范围为\[1111111111111,9999999999999\] **默认取值** 不涉及 | 表4MetricInfo | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | namespace | 是 | String | **参数解释** 服务命名空间，样例：弹性云服务器的命名空间为SYS.ECS。 各服务命名空间请参阅[支持监控的服务列表](https://support.huaweicloud.com/api-ces/ces_03_0059.html)。 **约束限制** 不涉及 **取值范围** 格式为service.item，service和item以点号拼接组成。 service和item必须以字母（大写或小写）开头，后面可以跟零个或多个字母（大写或小写）、数字、下划线（_），长度为\[3,32\]个字符 **默认取值** 不涉及 | | metric_name | 是 | String | **参数解释**： 指标ID，例如弹性云服务器的监控指标CPU使用率，对应的metric_name为cpu_util。各服务资源的指标名称，请参阅具体云服务的文档。您可以直接从[支持监控的服务列表](https://support.huaweicloud.com/api-ces/ces_03_0059.html)页面导航至相应文档。 **约束限制**： 不涉及。 **取值范围**： 必须以字母开头，只能包含0-9/a-z/A-Z/_/-；如：弹性云服务器中的监控指标cpu_util，表示弹性服务器的CPU使用率；文档数据库中的指标mongo001_command_ps，表示command执行频率。字符串长度为\[1,96\]。 **默认取值**： 不涉及。 | | dimensions | 是 | Array of [MetricsDimension] objects | **参数解释** 指标维度 **约束限制** 包含的指标维度对象个数为\[1,4\] | 表5MetricsDimension | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释** 资源维度，如：弹性云服务器，则维度为instance_id；目前最大支持4个维度，各服务资源的维度名称，请参阅具体云服务的文档。您可以直接从[支持监控的服务列表](https://support.huaweicloud.com/api-ces/ces_03_0059.html)页面导航至相应文档。 **约束限制** 不涉及 **取值范围** 由字母开头，后面可以包含字母、数字、_或-，长度为\[1,32\]个字符 **默认取值** 不涉及 | | value | 是 | String | **参数解释** 资源维度值，为资源的实例ID，如：4270ff17-aba3-4138-89fa-820594c39755。 **约束限制** 不涉及 **取值范围** 长度为\[1,256\]个字符 **默认取值** 不涉及 | #### 响应参数 **状态码：200** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | metrics | Array of [BatchMetricData] objects | **参数解释** 监控指标响应体 | 表7BatchMetricData | 参数 | 参数类型 | 描述 | |:---|:---|:---| | unit | String | **参数解释** 指标单位 **取值范围** 不涉及 | | datapoints | Array of [DatapointForBatchMetric] objects | **参数解释** 指标数据列表。由于查询数据时，云监控会根据所选择的聚合粒度向前取整from参数，所以datapoints中包含的数据点有可能会多于预期，最多返回3000个数据点（响应参数metrics属性对应对象datapoints属性累加最多返回3000个数据点） | | namespace | String | **参数解释** 服务命名空间 **取值范围** 不涉及 | | metric_name | String | **参数解释** 指标名称，例如弹性云服务器监控指标中的cpu_util。 **取值范围** 不涉及 | | dimensions | Array of [MetricsDimensionResp] objects | **参数解释** 服务维度列表 | 表8DatapointForBatchMetric | 参数 | 参数类型 | 描述 | |:---|:---|:---| | max | Double | **参数解释** 聚合周期内指标数据的最大值 **取值范围** 不涉及 | | min | Double | **参数解释** 聚合周期内指标数据的最小值 **取值范围** 不涉及 | | average | Double | **参数解释** 聚合周期内指标数据的平均值 **取值范围** 不涉及 | | sum | Double | **参数解释** 聚合周期内指标数据的求和值 **取值范围** 不涉及 | | variance | Double | **参数解释** 聚合周期内指标数据的方差 **取值范围** 不涉及 | | timestamp | Long | **参数解释** 指标采集时间，UNIX时间戳，单位毫秒 **取值范围** 不涉及 | 表9MetricsDimensionResp | 参数 | 参数类型 | 描述 | |:---|:---|:---| | name | String | **参数解释** 资源维度，如：弹性云服务器，则维度为instance_id；目前最大支持4个维度，各服务资源的维度名称，请参阅具体云服务的文档。您可以直接从[支持监控的服务列表](https://support.huaweicloud.com/api-ces/ces_03_0059.html)页面导航至相应文档。 **取值范围** 由字母开头，后面可以包含字母、数字、_或-，长度为\[1,32\]个字符 | | value | String | **参数解释** 资源维度值，为资源的实例ID，如：4270ff17-aba3-4138-89fa-820594c39755。 **取值范围** 长度为\[1,256\]个字符 | **状态码：400** 表10响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | - | String | 请求错误。 | **状态码：401** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | - | String | 未提供认证信息，或认证信息错误。 | **状态码：403** 表12响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | - | String | 请求页面被禁止访问。 | **状态码：408** 表13响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | - | String | 请求超出了服务器的等待时间。 | **状态码：429** 表14响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | - | String | 请求过多。 | **状态码：500** 表15响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | - | String | 请求未完成，服务异常。 | **状态码：503** 表16响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | - | String | 系统暂时不可用，请求受限。 | #### 请求示例 ``` { "metrics" : [ { "namespace" : "MINE.APP", "dimensions" : [ { "name" : "instance_id", "value" : "33328f02-3814-422e-b688-bfdba93d4050" } ], "metric_name" : "cpu_util" }, { "namespace" : "MINE.APP", "dimensions" : [ { "name" : "instance_id", "value" : "33328f02-3814-422e-b688-bfdba93d4051" } ], "metric_name" : "cpu_util" } ], "from" : 1484153313000, "to" : 1484653313000, "period" : "1", "filter" : "average" } ``` #### 响应示例 **状态码：200** OK ``` { "metrics" : [ { "unit" : "request/s", "datapoints" : [ { "average" : 0, "timestamp" : 1484401920000 }, { "average" : 1, "timestamp" : 1484407920000 } ], "namespace" : "MINE.APP", "dimensions" : [ { "name" : "instance_id", "value" : "33328f02-3814-422e-b688-bfdba93d4050" } ], "metric_name" : "cpu_util" }, { "unit" : "request/s", "datapoints" : [ { "average" : 2.3, "timestamp" : 1484401920000 }, { "average" : 1.2, "timestamp" : 1484407920000 } ], "namespace" : "MINE.APP", "dimensions" : [ { "name" : "instance_id", "value" : "33328f02-3814-422e-b688-bfdba93d4051" } ], "metric_name" : "cpu_util" } ] } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 408 | Request Timeout | | 429 | Too Many Requests | | 500 | Internal Server Error | | 503 | Service Unavailable | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-ces/ErrorCode.html)。