適用於 JavaScript 的 Azure Monitor 查詢指標用戶端庫 - 版本 1.0.0

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 監視器實例。若要執行測試，您必須執行：

rush update
rush build -t @azure/monitor-query-metrics
cd into sdk/monitor/monitor-query-metrics
將 sample.env 檔案複製到 .env
.env在編輯器中打開檔並填寫值。
npm run test。

有關更多詳細資訊，請查看我們的 tests 資料夾。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-08-13