你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

如何从指标 API 迁移到 getBatch API

项目
10/15/2024

重度使用指标 API 可能会导致限制或性能问题。通过迁移到 metrics:getBatch API，可以在单个 REST 请求中查询多个资源。这两个 API 共享一组通用的查询参数和响应格式，便于迁移。

请求格式

metrics:getBatch API 请求的格式如下：

POST /subscriptions/<subscriptionId>/metrics:getBatch?metricNamespace=<resource type namespace>&api-version=2023-10-01
Host: <region>.metrics.monitor.azure.com
Content-Type: application/json
Authorization: Bearer <token>
{
   "resourceids":[<comma separated list of resource IDs>]
}

例如，

POST /subscriptions/12345678-1234-1234-1234-123456789abc/metrics:getBatch?metricNamespace=microsoft.compute/virtualMachines&api-version=2023-10-01
Host: eastus.metrics.monitor.azure.com
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhb...TaXzf6tmC4jhog
{
    "resourceids":["/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/rg-vms-01/providers/Microsoft.Compute/virtualMachines/vmss-001_41df4bb9",
    "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/rg-vms-02/providers/Microsoft.Compute/virtualMachines/vmss-001_c1187e2f"
]
}

批处理限制

在确定 metrics:getBatch API 是否适合你的方案时，请考虑以下限制，它们用于规定哪些资源可以一起批处理。

批处理中的所有资源都必须位于同一订阅中。
批处理中的所有资源都必须位于同一 Azure 区域。
批处理中的所有资源都必须是同一资源类型。

为帮助识别满足这些条件的资源组，请使用 Azure Resource Graph 资源管理器或通过 Azure 资源管理器资源查询 API 运行以下 Azure Resource Graph 查询。

    resources
    | project id, subscriptionId, ['type'], location
    | order by subscriptionId, ['type'], location

请求转换步骤

若要将现有指标 API 调用转换为 metric:getBatch API 调用，请执行以下步骤：

假设正在使用以下 API 调用来请求指标：

GET https://management.azure.com/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z&interval=PT6H&metricNamespace=microsoft.storage%2Fstorageaccounts&metricnames=Ingress,Egress&aggregation=total,average,minimum,maximum&top=10&orderby=total desc&$filter=ApiName eq '*'&api-version=2019-07-01

更改主机名。
使用以下格式将 Azure Monitor 指标数据平面的 management.azure.com 替换为区域终结点：<region>.metrics.monitor.azure.com，其中 region 是请求其指标的资源的区域。例如，如果资源位于 westus2 中，则主机名为 westus2.metrics.monitor.azure.com。
更改 API 名称和路径。
metrics:getBatch API 是订阅级别的 POST API。请求其指标的资源在请求正文而不是 URL 路径中指定。
更改 URL 路径，如下所示：
从 /subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics
到 /subscriptions/12345678-1234-1234-1234-123456789abc/metrics:getBatch
metrics:getBatch 需要 metricNamespace 查询参数。对于 Azure 标准指标，命名空间名称通常是指定的资源的资源类型。若要检查要使用的命名空间值，请参阅指标命名空间 API
从使用 timespan 查询参数改为使用 starttime 和 endtime。例如，?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z 变为 ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z。
按如下所示更新 api-version 查询参数：&api-version=2023-10-01
筛选器查询参数在 metrics:getBatch API 中没有 $ 前缀。将查询参数从 $filter= 更改为 filter=。

metrics:getBatch API 是一个 POST 调用，其正文包含以下格式的以逗号分隔的 resourceId 列表：例如：

    {
      "resourceids": [
        // <comma separated list of resource ids>
      ]
    }

例如：

{
  "resourceids": [
    "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount"
  ]
}

每次调用最多可以指定 50 个唯一资源 ID。每个资源必须属于同一订阅、区域，并且同属一种资源类型。

重要

正文中的 resourceids 对象属性必须为小写。
确保数组列表中最后一个 resourceid 没有尾随逗号。

转换后的批处理请求

以下示例演示转换后的批处理请求。

    POST https://westus2.metrics.monitor.azure.com/subscriptions/12345678-1234-1234-1234-123456789abc/metrics:getBatch?starttime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z&interval=PT6H&metricNamespace=microsoft.storage%2Fstorageaccounts&metricnames=Ingress,Egress&aggregation=total,average,minimum,maximum&top=10&orderby=total desc&filter=ApiName eq '*'&api-version=2023-10-01
        
    {
      "resourceids": [
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount",
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample2-test-rg/providers/Microsoft.Storage/storageAccounts/eax252qtemplate",
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3diag",
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3prefile",
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3tipstorage",
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3backups/providers/Microsoft.Storage/storageAccounts/pod01account1"
      ]
    }

响应格式

metrics:getBatch API 的响应格式采用以下格式封装单个指标调用响应的列表：

{
  "values": [
      // <One individual metrics response per requested resourceId>
  ]
}

已在metrics:getBatch API 响应中将 resourceid 属性添加到每个资源的指标列表中。

下面显示了示例响应格式。

单个响应
metrics:getBatch 响应

{
  "cost": 11516,
  "startime": "2023-04-20T12:00:00Z",
  "endtime": "2023-04-22T12:00:00Z",
  "interval": "P1D",
  "value": [
    {
      "id": "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/Microsoft.Insights/metrics/Ingress",
      "type": "Microsoft.Insights/metrics",
      "name": {
        "value": "Ingress",
        "localizedValue": "Ingress"
      },
      "displayDescription": "The amount of ingress data, in bytes. This number includes ingress from an external client into Azure Storage as well as ingress within Azure.",
      "unit": "Bytes",
      "timeseries": [
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "EntityGroupTransaction"
            }
          ],
          "data": [
            {
              "timeStamp": "2023-04-20T12:00:00Z",
              "total": 1737897,
              "average": 5891.17627118644,
              "minimum": 1674,
              "maximum": 10976
            },
            {
              "timeStamp": "2023-04-21T12:00:00Z",
              "total": 1712543,
              "average": 5946.329861111111,
              "minimum": 1674,
              "maximum": 10980
            }
          ]
        },
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "GetBlobServiceProperties"
            }
          ],
          "data": [
            {
              "timeStamp": "2023-04-20T12:00:00Z",
              "total": 1284,
              "average": 321,
              "minimum": 321,
              "maximum": 321
            },
            {
              "timeStamp": "2023-04-21T12:00:00Z",
              "total": 1926,
              "average": 321,
              "minimum": 321,
              "maximum": 321
            }
          ]
        }
      ],
      "errorCode": "Success"
    },
    {
      "id": "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/Microsoft.Insights/metrics/Egress",
      "type": "Microsoft.Insights/metrics",
      "name": {
        "value": "Egress",
        "localizedValue": "Egress"
      },
      "displayDescription": "The amount of egress data. This number includes egress to external client from Azure Storage as well as egress within Azure. As a result, this number does not reflect billable egress.",
      "unit": "Bytes",
      "timeseries": [
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "EntityGroupTransaction"
            }
          ],
          "data": [
            {
              "timeStamp": "2023-04-20T12:00:00Z",
              "total": 249603,
              "average": 846.1118644067797,
              "minimum": 839,
              "maximum": 1150
            },
            {
              "timeStamp": "2023-04-21T12:00:00Z",
              "total": 244652,
              "average": 849.4861111111111,
              "minimum": 839,
              "maximum": 1150
            }
          ]
        },
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "GetBlobServiceProperties"
            }
          ],
          "data": [
            {
              "timeStamp": "2023-04-20T12:00:00Z",
              "total": 3772,
              "average": 943,
              "minimum": 943,
              "maximum": 943
            },
            {
              "timeStamp": "2023-04-21T12:00:00Z",
              "total": 5658,
              "average": 943,
              "minimum": 943,
              "maximum": 943
            }
          ]
        }
      ],
      "errorCode": "Success"
    }
  ],
  "namespace": "microsoft.storage/storageaccounts",
  "resourceregion": "westus2"
}

{
"values": [
  {
      "cost": 11516,
      "starttime": "2023-04-20T12:00:00Z",
      "endtime": "2023-04-22T12:00:00Z",
      "interval": "P1D",
      "value": [
        {
          "id": "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/Microsoft.Insights/metrics/Ingress",
          "type": "Microsoft.Insights/metrics",
          "name": {
            "value": "Ingress",
            "localizedValue": "Ingress"
          },
          "displayDescription": "The amount of ingress data, in bytes. This number includes ingress from an external client into Azure Storage as well as ingress within Azure.",
          "unit": "Bytes",
          "timeseries": [
            {
              "metadatavalues": [
                {
                  "name": {
                    "value": "apiname",
                    "localizedValue": "apiname"
                  },
                  "value": "EntityGroupTransaction"
                }
              ],
              "data": [
                {
                  "timeStamp": "2023-04-20T12:00:00Z",
                  "total": 1737897,
                  "average": 5891.17627118644,
                  "minimum": 1674,
                  "maximum": 10976
                },
                {
                  "timeStamp": "2023-04-21T12:00:00Z",
                  "total": 1712543,
                  "average": 5946.329861111111,
                  "minimum": 1674,
                  "maximum": 10980
                }
              ]
            },
            {
              "metadatavalues": [
                {
                  "name": {
                    "value": "apiname",
                    "localizedValue": "apiname"
                  },
                  "value": "GetBlobServiceProperties"
                }
              ],
              "data": [
                {
                  "timeStamp": "2023-04-20T12:00:00Z",
                  "total": 1284,
                  "average": 321,
                  "minimum": 321,
                  "maximum": 321
                },
                {
                  "timeStamp": "2023-04-21T12:00:00Z",
                  "total": 1926,
                  "average": 321,
                  "minimum": 321,
                  "maximum": 321
                }
              ]
            }
          ],
          "errorCode": "Success"
        },
        {
          "id": "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/Microsoft.Insights/metrics/Egress",
          "type": "Microsoft.Insights/metrics",
          "name": {
            "value": "Egress",
            "localizedValue": "Egress"
          },
          "displayDescription": "The amount of egress data. This number includes egress to external client from Azure Storage as well as egress within Azure. As a result, this number does not reflect billable egress.",
          "unit": "Bytes",
          "timeseries": [
            {
              "metadatavalues": [
                {
                  "name": {
                    "value": "apiname",
                    "localizedValue": "apiname"
                  },
                  "value": "EntityGroupTransaction"
                }
              ],
              "data": [
                {
                  "timeStamp": "2023-04-20T12:00:00Z",
                  "total": 249603,
                  "average": 846.1118644067797,
                  "minimum": 839,
                  "maximum": 1150
                },
                {
                  "timeStamp": "2023-04-21T12:00:00Z",
                  "total": 244652,
                  "average": 849.4861111111111,
                  "minimum": 839,
                  "maximum": 1150
                }
              ]
            },
            {
              "metadatavalues": [
                {
                  "name": {
                    "value": "apiname",
                    "localizedValue": "apiname"
                  },
                  "value": "GetBlobServiceProperties"
                }
              ],
              "data": [
                {
                  "timeStamp": "2023-04-20T12:00:00Z",
                  "total": 3772,
                  "average": 943,
                  "minimum": 943,
                  "maximum": 943
                },
                {
                  "timeStamp": "2023-04-21T12:00:00Z",
                  "total": 5658,
                  "average": 943,
                  "minimum": 943,
                  "maximum": 943
                }
              ]
            }
          ],
          "errorCode": "Success"
        }
      ],
      "namespace": "microsoft.storage/storageaccounts",
      "resourceregion": "westus2",
      "resourceid": "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount"
    },
    {
      "cost": 11516,
      "starttime": "2023-04-20T12:00:00Z",
      "endtime": "2023-04-22T12:00:00Z",
      "interval": "P1D",
      "value": [
        {
          "id": "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3diag/providers/Microsoft.Insights/metrics/Ingress",
          "type": "Microsoft.Insights/metrics",
          "name": {
            "value": "Ingress",
            "localizedValue": "Ingress"
          },
          "displayDescription": "The amount of ingress data, in bytes. This number includes ingress from an external client into Azure Storage as well as ingress within Azure.",
          "unit": "Bytes",
          "timeseries": [
            {
              "metadatavalues": [
                {
                  "name": {
                    "value": "apiname",
                    "localizedValue": "apiname"
                  },
                  "value": "EntityGroupTransaction"
                }
              ],
              "data": [
                {
                  "timeStamp": "2023-04-20T12:00:00Z",
                  "total": 867509,
                  "average": 5941.842465753424,
                  "minimum": 1668,
                  "maximum": 10964
                },
                {
                  "timeStamp": "2023-04-21T12:00:00Z",
                  "total": 861018,
                  "average": 5979.291666666667,
                  "minimum": 1668,
                  "maximum": 10964
                }
              ]
            },
            {
              "metadatavalues": [
                {
                  "name": {
                    "value": "apiname",
                    "localizedValue": "apiname"
                  },
                  "value": "GetBlobServiceProperties"
                }
              ],
              "data": [
                {
                  "timeStamp": "2023-04-20T12:00:00Z",
                  "total": 1268,
                  "average": 317,
                  "minimum": 312,
                  "maximum": 332
                },
                {
                  "timeStamp": "2023-04-21T12:00:00Z",
                  "total": 1560,
                  "average": 312,
                  "minimum": 312,
                  "maximum": 312
                }
              ]
            }
          ],
          "errorCode": "Success"
        },
        {
          "id": "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3diag/providers/Microsoft.Insights/metrics/Egress",
          "type": "Microsoft.Insights/metrics",
          "name": {
            "value": "Egress",
            "localizedValue": "Egress"
          },
          "displayDescription": "The amount of egress data. This number includes egress to external client from Azure Storage as well as egress within Azure. As a result, this number does not reflect billable egress.",
          "unit": "Bytes",
          "timeseries": [
            {
              "metadatavalues": [
                {
                  "name": {
                    "value": "apiname",
                    "localizedValue": "apiname"
                  },
                  "value": "EntityGroupTransaction"
                }
              ],
              "data": [
                {
                  "timeStamp": "2023-04-20T12:00:00Z",
                  "total": 124316,
                  "average": 851.4794520547945,
                  "minimum": 839,
                  "maximum": 1150
                },
                {
                  "timeStamp": "2023-04-21T12:00:00Z",
                  "total": 122943,
                  "average": 853.7708333333334,
                  "minimum": 839,
                  "maximum": 1150
                }
              ]
            },
            {
              "metadatavalues": [
                {
                  "name": {
                    "value": "apiname",
                    "localizedValue": "apiname"
                  },
                  "value": "GetBlobServiceProperties"
                }
              ],
              "data": [
                {
                  "timeStamp": "2023-04-20T12:00:00Z",
                  "total": 3384,
                  "average": 846,
                  "minimum": 846,
                  "maximum": 846
                },
                {
                  "timeStamp": "2023-04-21T12:00:00Z",
                  "total": 4230,
                  "average": 846,
                  "minimum": 846,
                  "maximum": 846
                }
              ]
            }
          ],
          "errorCode": "Success"
        }
      ],
      "namespace": "microsoft.storage/storageaccounts",
      "resourceregion": "westus2",
      "resourceid": "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3diag"
    }
  ]
}

错误响应更改

在 metrics:getBatch 错误响应中，错误内容包装在响应的顶级“error”属性中。例如，

指标 API 错误响应

{
  "code": "BadRequest",
  "message": "Metric: Ingress does not support requested dimension combination: apiname2, supported ones are: GeoType,ApiName,Authentication, TraceId: {6666aaaa-77bb-cccc-dd88-eeeeee999999}"
}

Batch API 错误响应：

{
  "error": {
    "code": "BadRequest",
    "message": "Metric: Egress does not support requested dimension combination: apiname2, supported ones are: GeoType,ApiName,Authentication, TraceId: {6666aaaa-77bb-cccc-dd88-eeeeee999999}"
  }
}

疑难解答

返回的空时序 "timeseries": []
- 当没有可用于指定时间范围和筛选器的数据时，将返回空时序。最常见的原因是指定的时间范围不包含任何数据。例如，如果时间范围设置为将来的日期。
- 另一个常见原因是指定的筛选器与任何资源不匹配。例如，如果筛选器指定订阅和区域组合中的任何资源上不存在的维度值，则返回 "timeseries": []。
通配符筛选器
使用通配符筛选器（例如 Microsoft.ResourceId eq '*'）会导致 API 返回订阅和区域中每个 resourceId 的时序。如果订阅和区域组合不包含任何资源，则返回空时序。没有通配符筛选器的相同查询将返回单个时序，将请求的指标聚合到请求的维度上，例如订阅和区域。
目前不支持自定义指标
metrics:getBatch API 不支持查询自定义指标，也不支持查询指标命名空间名称不是资源类型的查询。使用命名空间“azure.vm.windows.guestmetrics”或“azure.vm.linux.guestmetrics”的 VM 来宾 OS 指标就是这种情况。
顶部参数按指定的资源 ID 应用。
在批处理 API 的背景下，顶部参数的工作原理可能有点令人困惑。它不会对整个调用返回的总时序实施限制，而是强制实施每个资源 ID 的每个指标返回的总时序。如果批处理查询指定了多个“*”筛选器，具有 2 个指标和 4 个资源 ID（前 5 个）。该查询返回的最大可能时序为 40，即 2x4x5 时序。

401 授权错误

单个指标 API 要求用户对要查询的资源具有监视读取者权限。由于 metrics:getBatch API 是订阅级 API，因此用户必须具有查询订阅的监视读者权限才能使用批处理 API。即使用户在批处理 API 中查询的所有资源上都有监视读取者权限，如果用户在订阅本身上没有监视读取者权限，请求也会失败。

529 限制错误

虽然数据平面批处理 API 旨在帮助缓解限制问题，但仍会出现 529 错误代码，表示指标后端当前正在限制某些客户。建议的操作是实现指数退避重试方案。

Paging

metrics:getBatch API 不支持分页。此 API 最常见的用例是，在最新时间范围内，针对相同的指标和资源，每隔几分钟调用一次。低延迟是一个重要考虑因素，因此许多客户会尽可能将其查询并行化。分页会强制客户进入顺序调用模式，这会导致额外的查询延迟。如果分页可以帮助处理请求返回的指标数据量，建议将查询拆分为多个并行查询。

计费

是，所有指标数据平面和批处理调用都计费。有关详细信息，请参阅基本日志搜索查询中的 Azure Monitor 原生指标部分。

通过