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

适用于 JavaScript 的 Azure Monitor 查询指标客户端库 - 版本 1.0.0

2025-08-13

Azure Monitor 查询指标客户端库用于针对 Azure Monitor 的指标数据平台执行只读查询：

Metrics （指标） – 将受监控资源中的数值数据收集到时间序列数据库中。指标是定期收集的数值，用于描述系统在某一特定时间的某些情况。指标是轻量级指标，能够支持准实时方案，使它们可用于警报和快速检测问题。

从咨询@azure/monitor-query迁移 ⚠ ️

查看迁移指南，了解如何将应用程序代码从原始 @azure/monitor-query 包更新到库的 @azure/monitor-query-metrics 详细说明。

资源：

入门指南

支持的环境

LTS 版本的 Node.js
Safari、Chrome、Microsoft Edge 和 Firefox 的最新版本

有关详细信息，请参阅我们的支持政策。

先决条件

一个 Azure 订阅
TokenCredential 实现，例如 Azure 标识库凭据类型。
若要查询指标，需要任何类型的 Azure 资源（存储帐户、Key Vault、Cosmos DB 等）。

安装软件包

使用 npm 安装适用于 JavaScript 的 Azure Monitor 查询指标客户端库：

npm install --save @azure/monitor-query-metrics

创建客户端

需要经过身份验证的客户端才能查询指标。为了进行身份验证，以下示例使用 @azure/identity 包中的 DefaultAzureCredential。

import { DefaultAzureCredential } from "@azure/identity";
import { MetricsClient } from "@azure/monitor-query-metrics";

const credential = new DefaultAzureCredential();

// Create a MetricsClient
const endpoint = " https://<endpoint>.monitor.azure.com/";
const metricsClient = new MetricsClient(endpoint, credential);

为 Azure 主权云配置客户端

默认情况下，库的客户端配置为使用 Azure 公有云。若要改用主权云，在实例化客户端时提供正确的终结点和受众值。例如：

import { DefaultAzureCredential } from "@azure/identity";
import { MetricsClient } from "@azure/monitor-query-metrics";

const credential = new DefaultAzureCredential();

// Create a MetricsClient
const endpoint = " https://<endpoint>.monitor.azure.cn/";
const metricsClient = new MetricsClient(endpoint, credential, {
  audience: "https://monitor.azure.cn/.default",
});

执行查询

有关指标查询的示例，请参阅示例部分。

重要概念

指标数据结构

每个指标值集都是具有以下特征的时序：

收集值的时间
与值关联的资源
一个命名空间，其作用类似于指标的类别
指标名称
值本身
某些指标具有多个维度，如多维指标中所述。自定义指标最多可以有 10 个维度。

例子

指标查询
- 处理指标查询响应

指标查询

若要查询一个或多个 Azure 资源的指标，请使用 queryResources 的方法 MetricsClient。创建客户端时，此方法需要区域终结点。例如，https://westus3.metrics.monitor.azure.com。

每个 Azure 资源必须驻留在以下位置：

创建客户端时指定的终结点所在的区域。
相同的 Azure 订阅。

资源 ID 必须是要查询指标的资源的 ID。它通常是 /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

若要查找资源 ID/URI，请执行以下作：

导航到 Azure 门户中的资源页。
选择“概述”部分中的“JSON 视图”链接。
复制 JSON 视图顶部的 “资源 ID” 文本框中的值。

此外：

用户必须有权在 Azure 订阅级别读取监视数据。例如，要查询的订阅上的 Monitoring Reader 角色。
必须提供包含要查询的指标的指标命名空间。有关指标命名空间的列表，请参阅按资源类型支持的指标和日志类别。

import { DefaultAzureCredential } from "@azure/identity";
import { MetricsClient } from "@azure/monitor-query-metrics";

const resourceIds = [
  "/subscriptions/0000000-0000-000-0000-000000/resourceGroups/test/providers/Microsoft.OperationalInsights/workspaces/test-logs",
  "/subscriptions/0000000-0000-000-0000-000000/resourceGroups/test/providers/Microsoft.OperationalInsights/workspaces/test-logs2",
];
const metricsNamespace = "Microsoft.OperationalInsights/workspaces";
const metricNames = ["Heartbeat"];
const endpoint = "https://westus3.metrics.monitor.azure.com";

const credential = new DefaultAzureCredential();
const metricsClient = new MetricsClient(endpoint, credential);

const result = await metricsClient.queryResources(resourceIds, metricNames, metricsNamespace, {
  aggregation: "Count",
});

console.log(`Retrieved metrics for ${result.length} resources`);
for (const resource of result) {
  console.log(`Resource: ${resource.resourceId}`);
  console.log(`Metrics: ${resource.metrics.length}`);
}

处理指标查询响应

指标查询 API 返回对象列表 MetricsQueryResult 。该 MetricsQueryResult 对象包含属性，例如类型对象列表 Metric、 granularity、 namespace和 timespan。 Metric可以使用 property 访问 metrics objects 列表。此列表中的每个 Metric 对象都包含一个对象列表 TimeSeriesElement 。每个对象都 TimeSeriesElement 包含 data 和 metadatavalues 属性。在视觉形式中，响应的对象层次结构类似于以下结构：

MetricsQueryResult
|---granularity
|---timespan
|---cost
|---namespace
|---resourceRegion
|---metrics (list of `Metric` objects)
    |---id
    |---type
    |---name
    |---unit
    |---timeseries (list of `TimeSeriesElement` objects)
        |---metadatavalues
        |---data (list of data points)

注意： 每个返回的 MetricsQueryResult 顺序与参数中的 resourceIds 相应资源相同。如果查询了多个不同的指标，则按发送的顺序 metricNames 返回指标。

处理响应示例：

import { DefaultAzureCredential } from "@azure/identity";
import { MetricsClient, Durations } from "@azure/monitor-query-metrics";

const resourceIds = [
  "/subscriptions/0000000-0000-000-0000-000000/resourceGroups/test/providers/Microsoft.OperationalInsights/workspaces/test-logs",
];
const metricsNamespace = "Microsoft.OperationalInsights/workspaces";
const metricNames = ["Heartbeat"];
const endpoint = "https://westus3.metrics.monitor.azure.com";

const credential = new DefaultAzureCredential();
const metricsClient = new MetricsClient(endpoint, credential);

const endTime = new Date();
const startTime = new Date(endTime.getTime() - 60 * 60 * 1000); // 1 hour ago

const result = await metricsClient.queryResources(resourceIds, metricNames, metricsNamespace, {
  aggregation: "Count,Average", // Multiple aggregations
  startTime: startTime,
  endTime: endTime,
  interval: Durations.fiveMinutes,
  top: 10, // Limit results
  orderBy: "count desc", // Sort by count descending
  filter: "Computer eq '*'", // Filter criteria
});

console.log(`Retrieved ${result.length} resources with advanced filtering`);
for (const resource of result) {
  for (const metric of resource.metrics) {
    console.log(`Metric: ${metric.name}`);
    console.log(`Time series count: ${metric.timeseries.length}`);
  }
}

有关可用于每种 Azure 资源类型的指标和维度的清单，请参阅 Azure Monitor 支持的指标。

故障排除

要诊断各种故障场景，请参阅故障排除指南。

后续步骤

若要了解有关 Azure Monitor 的详细信息，请参阅 Azure Monitor 服务文档。

贡献

若要参与此库，请阅读贡献指南了解有关如何生成和测试代码的详细信息。

本模块的测试是实时测试和单元测试的混合体，需要拥有 Azure Monitor 实例。若要执行测试，需要运行：

rush update
rush build -t @azure/monitor-query-metrics
cd into sdk/monitor/monitor-query-metrics
将 sample.env 文件复制到 .env
.env在编辑器中打开文件并填写值。
npm run test。

有关更多详细信息，请查看我们的 tests 文件夹。

反馈

此页面是否有帮助？