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

使用限制

• 调用接口前，请为子账号授权云监控只读权限 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

调试

请求参数

Instance

Dimension

Period说明

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

(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"
    ]
}

请求示例

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

POST https://open.volcengineapi.com?Action=GetMetricData&Version=2018-01-01
Content-Type: application/json
{
    "MetricName": "InTraffic",
    "Namespace": "VCM_EIP",
    "Period": "1m",
    "StartTime": 1648048800,
    "EndTime": 1648049400,
    "GroupBy": [
        ""
    ],
    "Instances": [
        {
            "Dimensions": [
                {
                    "Name": "ResourceID",
                    "Value": "eip-13fxxxx"
                }
            ]
        }
    ],
    "SubNamespace": "Instance"
}

返回参数

Data

MetricData

DataPoint

Dimension

返回示例

{
    "ResponseMetadata": {
        "Action": "GetMetricData",
        "Region": "cn-beijing",
        "Service": "volc_observe_boe",
        "Version": "2018-01-01",
        "RequestId": "20230604110420****100232280022D31"
    },
    "Result": {
        "Data": {
            "Unit": "Bytes",
            "Period": "1m",
            "EndTime": 1648049400,
            "Namespace": "VCM_EIP",
            "StartTime": 1648048800,
            "MetricName": "InTraffic",
            "DescriptionCN": "入方向流量",
            "DescriptionEN": "EIP In Traffic",
            "MetricDataResults": [
                {
                    "Legend": "eip_in_bytes",
                    "DataPoints": [
                        {
                            "Value": 864,
                            "Timestamp": 1648048800
                        }
                    ],
                    "Dimensions": [
                        {
                            "Name": "ResourceID",
                            "Value": "eip-13fxxxx"
                        }
                    ]
                }
            ]
        }
    }
}

错误码

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