查询指定指标在指定时间选段内聚合的时序数据。

使用限制

调用接口前，请为子账号授权云监控只读权限 CloudMonitorReadOnlyAccess，否则会报User is not authorized to perform: cloudmonitor:GetMetricData on resource错误。具体操作，请参见为IAM用户授权。

GetMetricData接口仅支持单指标查询，无法一次查询多个指标数据。

一个主账号及该账号下的 IAM 账号，1 秒内调用GetMetricData接口的次数不超过 20 次，否则将触发限流。

单请求最多支持批量拉取 50 个实例的监控数据，单请求的数据点数限制为 1440 个。

如果您需要调用的指标和对象较多，可能会因为限频导致拉取失败，建议尽量将请求按照时间维度均摊。

请求说明

云监控已在全球多个地域部署服务，旨在为您提供更稳定、低延迟的访问体验。您可以通过查阅服务地址文档，根据业务所在地选择最合适的接入点。

请求方式：POST

请求地址：https://cloudmonitor.cn-beijing.volcengineapi.com?Action=GetMetricData&Version=2018-01-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

参数	类型	是否必选	示例值	描述
Action	String	是	GetMetricData	接口名称。当前 API 的名称为 GetMetricData。
Version	String	是	2018-01-01	接口版本。当前 API 的版本为 2018-01-01。
StartTime	Integer	否	1648048800	查询的时间选段的开始时间，秒级时间戳，例如1632904500。
EndTime	Integer	否	1648049400	查询的时间选段的结束时间，秒级时间戳，例如1632904801。 EndTime需要 > StartTime。 EndTime不能输入未来时间。 EndTime < 产品允许查询天数 + StartTime。
Instances	Array of Instance	否	-	要查询的监控指标信息。存在多个 instance 时，instance 和 instance 之间的逻辑关系是 or。如果不传 instance 参数，会返回该地域下所有实例的监控数据。数据量较大可能会数据量较大可能会导致max-select-point超限，对业务产生影响，请谨慎操作。如果已报错，请参见错误码部分max-select-point原因和解决方案。
MetricName	String	否	InTraffic	要查询的监控指标名称。参见云监控指标查询下各产品的 MetricName。
Namespace	String	否	VCM_EIP	要查询的监控指标所属的产品空间。参见云监控指标查询下各产品的 Namespace。
Period	String	否	1m	查询数据的间隔粒度，支持秒（s）、分钟（m）、时（h）、天（d）和周（w）粒度。例如查询 10 分钟内的数据，并根据 1 分钟进行分割，则会返回 10 条数据。当时间选段较长时，不建议使用小单位作为间隔，否则将会导致数据集过大，可能会导致max-select-bucket超限，对业务产生影响，请谨慎操作。如果已报错，请参见错误码部分max-select-bucket原因和解决方案。关于传入Period后，StartTime、EndTime偏移的说明，请参见 Period 说明。
GroupBy	Array of String	否	AlternativeDimensionName	要查询的指标所使用的分组维度。参见云监控指标查询下各产品的 Dimensions。如果指标的 Dimension 列未标注可选，说明不存在可选 Dimension，默认所有 Dimension 都是必选，都会作为指标分组维度。说明必选的含义是无论是否传递这些 Dimension 参数，返回的维度都会以这些 Dimension 进行分组。以缓存数据库 Redis 版的指标AggregatedTotalQps为例，Dimension 列为 ResourceID,Node。当 Dimension 参数传递 Node，不传递 ReourceID 时：查询条件：Node=xxx and ResourceID=* 分组维度：Node,ResourceId 当 Dimension 参数传递 Node 和 ReourceID 时：查询条件：Node=xxx and ResouceId=yyy 分组维度：Node,ResourceId 如果指标的 Dimension 列标注了可选，说明存在可选 Dimension，使用时需要额外指定 GroupBy 参数。示例请参见 GroupBy 说明。注意 SDK 必须升级到以下版本，才支持通过 GroupBy 筛选分组维度。 Python：1.0.37 版本以上 Go：1.0.97 版本以上 Java：0.1.75 版本以上
SubNamespace	String	否	Instance	要查询的指标所属的维度。SubNamespace在不同Namespace下的可选值不同，参见云监控指标查询下各产品的 SubNamespace。
StatisticsMethods	Array of String	否	avg	指定监控数据的统计聚合方式。目前支持的聚合方式： avg ：平均值聚合，对同一聚合分组下所有样本指标数值取算术平均值。 sum ：求和聚合，对同一聚合分组下全部指标数值做累加求和。 max ：最大值聚合，提取同一聚合分组内所有指标样本中的最大数值。 min ：最小值聚合，提取同一聚合分组内所有指标样本中的最小数值。说明若配置多个聚合方式，返回结构中的 MetricDataResults 会根据配置的聚合方式分别返回结果，并通过 StatisticsMethods 标识当前结果对应的聚合方式。查询时，建议使用云监控指标查询中提供的统计方式，否则可能存在数据统计误差。

Instance

参数	类型	是否必选	示例值	描述
Dimensions	Array of Dimension	否	-	要查询的指标维度。参见云监控指标查询下各产品的 Dimensions。每个 Dimension 里只包含一组 KV。存在多个 Dimension 时，Dimension 和 Dimension 之间的逻辑关系是 and。

Dimension

参数	类型	是否必选	示例值	描述
Name	String	否	ResourceID	检索指标的 KEY。
Value	String	否	eip-13fxxxx	对应 KEY 的值。

Period说明

例如，查询 10 分钟内的数据，并根据 1 分钟进行分割，则会返回 10 条数据。

当时间选段较长时，不建议使用小单位作为间隔，否则将会导致数据集过大。后端具有大值拒绝限制，当传入的参数形成如下条件时，请求失败：

对于传入的StartTime、EndTime、Period组合，取值范围建议参考下表。

查询时间范围（EndTime-StartTime）	监控数据聚合周期（Period）
(0~6]小时	30秒
(6~24]小时	1分钟
(1~7]天	5分钟
(7~15]天	60分钟

当传入Period后，StartTime、EndTime参数将会被偏移。返回的数据集合中，时间将会转移至Period的整分处。整分处为某时间戳可以整除Period。

例如：

传入Period为 30s，则在当前分钟内，0s，30s 为整分点。

传入Period为 20s，则在当前分钟内，0s，20s，40s 为整分点。

传入Period为 10m，则在当前小时内，0m0s，10m0s，20m0s，30m0s，40m0s，50m0s 为整分点。

传入Period为 24h，则在当前时间段内，UTC+0 00:00:00 为整分点。

例如，StartTime为 2023-03-02 00:00:00，EndTime为 2023-03-05 00:00:00。

实际上，UTC 时间是StartTime为 2023-03-01 16:00:00，EndTime为 2023-03-04 16:00:00。

因此，返回的是 UTC 时间 2023-03-02 00:00:00，2023-03-03 00:00:00，2023-03-04 00:00:00 的数据。

StartTime总会向后偏移至最近一个整分点，EndTime总会向前偏移至整分点。因此返回的数据长度和数据时间点会有一定变化，但是StartTime和EndTime本身无变化，只是选段区间被偏移。

GroupBy说明

GroupBy 是查询指标所使用的分组维度。详情请参见云监控指标查询下各产品的 Dimensions。

如果指标的 Dimension 列未标注可选，表示不存在可选 Dimension，默认所有 Dimension 都是必选，都会作为指标分组维度。

必选是指无论是否传递这些 Dimension 参数，返回的维度都会以这些 Dimension 进行分组。

例如，缓存数据库 Redis 版的指标 AggregatedTotalQps，Dimension 列为 ResourceID,Node。

当 Dimension 参数传递 Node，不传递 ReourceID 时：

查询条件：Node=xxx and ResourceID=*

分组维度：Node,ResourceId

当 Dimension 参数传递 Node 和 ReourceID 时：

查询条件：Node=xxx and ResouceId=yyy

分组维度：Node,ResourceId

如果指标的 Dimension 列标注了可选，表示存在可选 Dimension，使用时需要额外指定 GroupBy 参数。

例如，云搜索服务的指标 CacheHitRatio，Dimension 列为 ResourceID,Node(可选)。多示例场景的配置示例如下：

请求示例

返回参数

参数	类型	示例值	描述
Data	Object of Data	-	返回数据。

Data

参数	类型	示例值	描述
Unit	String	Bytes	指标的单位。
Period	String	1m	查询的时间间隔粒度。 m：分钟 s：秒 h：小时 d：天 w：周
EndTime	Integer	1648049400	查询选段时间的结束时间戳，秒级时间戳。
Namespace	String	VCM_EIP	监控指标所属的产品空间。
StartTime	Integer	1648048800	查询选段时间的开始时间戳，秒级时间戳。
MetricName	String	InTraffic	查询的监控指标的名称。
DescriptionCN	String	入方向流量	查询指标的中文名。
DescriptionEN	String	EIP In Traffic	查询指标的英文名。
MetricDataResults	Array of MetricData	-	查询到的指标数据。

MetricData

参数	类型	示例值	描述
Legend	String	eip_in_bytes	查询指标 MetricName 的别名。
DataPoints	Array of DataPoint	-	在指定时间选段内，指定指标的聚合时序数据。
Dimensions	Array of Dimension	-	查询条件。
StatisticsMethods	String	avg	MetricDataResults 查询结果中对应的聚合方式。目前支持的聚合方式包括： avg、sum、max、min。请求中指定多种聚合方式时，每种聚合方式分别生成一组结果，并通过该字段进行标识。

DataPoint

参数	类型	示例值	描述
Value	Float	864	数据值。
Timestamp	Integer	1648048800	数据采集的秒级时间戳。

Dimension

参数	类型	示例值	描述
Name	String	ResourceID	检索指标的 KEY。
Value	String	eip-13fxxxx	对应 KEY 的值。

返回示例

错误码

本接口无特有的错误码。更多信息请参见错误码。