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

使用限制

• 调用接口前，请为子账号授权云监控只读权限CloudMonitorReadOnlyAccess，否则会报错User is not authorized to perform: Volc_Observe:GetMetricsData on resource。具体操作请参见为IAM用户授权。
• GetMetricData接口仅支持单指标查询，无法一次查询多个指标数据。
• 一个主账号及该账号下的IAM账号，1秒内调用GetMetricData接口的次数不超过20次，否则将触发限流。
• 单请求最多支持批量拉取50个实例的监控数据，单请求的数据点数限制为1440个。
  如果您需要调用的指标和对象较多，可能会因为限频导致拉取失败，建议尽量将请求按照时间维度均摊。

请求说明

• 请求方式：POST
• 请求地址：https://open.volcengineapi.com?Action=GetMetricData&Version=2018-01-01

Header

ServiceName : Volc_Observe 
Region : cn-beijing 
AccessKey : xxx 
SecretKey : xxx

调试

请求参数

Query

Body

Instance

Dimension

Period说明

例如，查询10分钟内的数据，并根据1分钟进行分割，则会返回10条数据。
当时间选段较长时，不建议使用小单位作为间隔，否则将会导致数据集过大。后端具有大值拒绝限制，当传入的参数形成如下条件时，请求失败：

下述条件中 EndTime、StartTime 和 Period 的单位为：秒(s)
(EndTime - StartTime) / Period >= 5000

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

当传入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(可选)。多示例场景的配置示例如下：

  {
      "Instances": [
          {
              "Dimensions": [
                  {
                      "Name": "ResourceID",
                      "Value": "eip-13fxxxx"
                  },
                  {
                      "Name": "Node",
                      "Value": "xxxx"
                  }
              ]
          },
          {
              "Dimensions": [
                  {
                      "Name": "ResourceID",
                      "Value": "eip-14dxxxx"
                  },
                  {
                      "Name": "Node",
                      "Value": "xxxx"
                  }
              ]
          }
      ],
      "GroupBy": [
          "Node"
      ]
  }
  

返回参数

Data

MetricData

Dimension

DataPoint

请求示例

全域云产品列表如下所示：

POST https://open.volcengineapi.com?Action=GetMetricData&Version=2018-01-01
ServiceName: Volc_Observe
Region: cn-beijing
AccessKey: xxx
SecretKey: xxx

{
    "MetricName": "InTraffic",
    "StartTime": 1648048800,
    "EndTime": 1648049400,
    "Period": "1m",
    "Namespace": "VCM_EIP",
    "Instances": [
        {
            "Dimensions": [
                {
                    "Name": "ResourceID",
                    "Value": "eip-13fxxxx"
                }
            ]
        },
        {
            "Dimensions": [
                {
                    "Name": "ResourceID",
                    "Value": "eip-14dxxxx"
                }
            ]
        }
    ],
    "SubNamespace": "Instance"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230****708A9",
        "Action": "GetMetricData",
        "Version": "2018-01-01",
        "Service": "",
        "Region": ""
    },
    "Result": {
        "Data": {
            "Namespace": "VCM_EIP",
            "MetricName": "InTraffic",
            "DescriptionCN": "入方向流量",
            "DescriptionEN": "EIP In Traffic",
            "Period": "1m",
            "StartTime": 1648048800,
            "EndTime": 1648049400,
            "Unit": "Bytes(SI)",
            "MetricDataResults": [
                {
                    "Legend": "eip_in_bytes",
                    "Dimensions": [
                        {
                            "Name": "ResourceID",
                            "Value": "eip-13fxxxx"
                        }
                    ],
                    "DataPoints": [
                        {
                            "Timestamp": 1648048800,
                            "Value": 864
                        },
                        {
                            "Timestamp": 1648048860,
                            "Value": 420
                        },
                        {
                            "Timestamp": 1648049340,
                            "Value": 720
                        }
                    ]
                },
                {
                    "Legend": "eip_in_bytes",
                    "Dimensions": [
                        {
                            "Name": "ResourceID",
                            "Value": "eip-14dfxxxx"
                        }
                    ],
                    "DataPoints": [
                        {
                            "Timestamp": 1648048800,
                            "Value": 833
                        },
                        {
                            "Timestamp": 1648048860,
                            "Value": 401
                        },
                        {
                            "Timestamp": 1648049340,
                            "Value": 799
                        }
                    ]
                }
            ]
        }
    }
}

错误码

本接口错误码如下表所示，公共错误码请参见错误码。