適用於 JavaScript 的 Azure Metrics Advisor 用戶端連結庫 - 1.0.0 版

發行項
01/10/2024

Metrics Advisor 是 Azure 認知服務的一部分，使用 AI 在時間序列資料中執行資料監視和異常偵測。服務會自動化將模型套用至資料的程序，並提供一組 Web 工作區的 API 來進行資料內嵌、異常偵測和診斷，您無需具備機器學習服務相關知識。使用 Metrics Advisor 可：

分析來自多個資料來源的多維度資料
識別異常並使其相互關聯
設定及微調資料所使用的異常偵測模型
診斷異常，並協助進行根本原因分析。

重要連結：

開始使用

目前支援的環境

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

如需詳細資訊，請參閱我們的支援原則。

必要條件

Azure 訂用帳戶。
現有的認知服務或 Metrics Advisor 資源。如果您需要建立資源，您可以使用 Azure 入口網站或 Azure CLI。

如果您使用 Azure CLI，請將與 <your-resource-name> 取代<your-resource-group-name>為您自己的唯一名稱：

az cognitiveservices account create --kind MetricsAdvisor --resource-group <your-resource-group-name> --name <your-resource-name> --sku <sku level> --location <location>

安裝 `@azure/ai-metrics-advisor` 套件

使用 npm安裝適用於 JavaScript 的 Azure Metrics Advisor 用戶端連結庫：

npm install @azure/ai-metrics-advisor

建立和驗證 `MetricsAdvisorClient` 或 `MetricsAdvisorAdministrationClient`

若要建立客戶端物件來存取 Metrics Advisor API，您需要 endpoint Metrics Advisor 資源和 credential的。 Metrics Advisor 用戶端會使用 Metrics Advisor 金鑰認證進行驗證。

您可以在 Azure 入口網站或使用下列 Azure CLI 代碼段，找到 Metrics Advisor 資源的端點：

az cognitiveservices account show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

使用訂用帳戶金鑰和 API 金鑰

您將需要兩個金鑰來驗證用戶端：

Metrics Advisor 資源的訂用帳戶密鑰。您可以在 Azure 入口網站中資源的 [金鑰和端點] 區段中找到此專案。
您的 Metrics Advisor 執行個體的 API 金鑰。您可以經由 Metrics Advisor 的入口網站，在左側導覽功能表的 [API 金鑰] 中找到這項資料。您可以在 Azure 入口網站中資源的 [概觀] 區段中找到入口網站的 URL。

使用 Azure 入口網站流覽至您的 Metrics Advisor 資源並擷取訂用帳戶密鑰，或使用下列 Azure CLI 代碼段：

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

此外，您也需要來自 Metrics Advisor 入口網站的每個使用者 API 金鑰。

擁有兩個金鑰和端點之後，您可以使用 MetricsAdvisorKeyCredential 類別來驗證用戶端，如下所示：

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorClient,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

const credential = new MetricsAdvisorKeyCredential("<subscription Key>", "<API key>");

const client = new MetricsAdvisorClient("<endpoint>", credential);
const adminClient = new MetricsAdvisorAdministrationClient("<endpoint>", credential);

使用 Azure 服務目錄

API 金鑰授權用於大部分的範例中，但您也可以使用 Azure 身分識別連結庫向 Azure Active Directory 驗證用戶端。若要使用如下所示的 DefaultAzureCredential 提供者或其他 Azure SDK 提供的認證提供者，請安裝 @azure/identity 套件：

npm install @azure/identity

若要使用服務主體進行驗證，您也必須註冊 AAD 應用程式，並將「認知服務使用者」角色指派給服務主體，以授與 Metrics Advisor 的存取權， (附注：其他角色，例如「擁有者」不會授與必要的許可權，只有「認知服務使用者」才能執行範例和範例程式代碼) 。

將 AAD 應用程式的用戶端識別碼、租使用者識別碼和客戶端密碼的值設定為環境變數：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET。我們也支援 Azure Active Directoty 認證驗證。您將需要 Azure 租使用者標識碼、Azure 用戶端識別碼和 Azure 用戶端密碼作為環境變數。

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorClient,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");
import { DefaultAzureCredential } from "@azure/identity";
const credential = new DefaultAzureCredential();
const client = new MetricsAdvisorClient("<endpoint>", credential);
const adminClient = new MetricsAdvisorAdministrationClient("<endpoint>", credential);

重要概念

MetricsAdvisorClient

MetricsAdvisorClient 是使用 Metrics Advisor 用戶端連結庫的開發人員的主要查詢介面。它提供異步方法來存取 Metrics Advisor 的特定用途，例如列出事件、擷取事件的根本原因、擷取服務擴充的原始時間序列數據和時間序列數據。

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient 是負責管理 Metrics Advisor 資源中實體的介面，例如管理數據摘要、異常偵測組態、異常警示設定。

數據摘要

資料摘要是計量建議程式從資料來源擷取的內容，例如 Cosmos DB 或 SQL Server。資料摘要包含下列資料列：

時間戳記
零或多個維度
一或多個量值

計量

計量是可量化的量值，用以監視及評估特定商務程序的狀態。此量值可由分割成維度的多個時間序列值組合而成。例如，Web 健康情況計量可包含使用者計數和美國市場的維度。

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration 是每個時間序列的必要專案，並判斷時間序列中的某個點是否為異常。

異常 & 事件

將偵測組態套用至計量之後， AnomalyIncident每當其內的任何數列都有 DataPointAnomaly時，就會產生。

警示

您可以設定哪些異常應該觸發 AnomalyAlert。您可以使用不同的設定來設定多個警示。例如，您可以針對對業務影響較低的異常建立警示，並針對更重要的警示建立另一個警示。

勾點

計量建議程式可讓您建立及訂閱即時警示。這些警示會透過因特網傳送，並使用通知攔截。

如需完整的概念清單，請參閱計量諮詢詞彙文件頁面。

範例

下一節提供數個 JavaScript 代碼段，說明 Metrics Advisor 用戶端連結庫中所使用的常見模式。

從範例數據源新增數據摘要
檢查擷取狀態
設定異常偵測組態
新增攔截以接收異常警示
設定警示設定
查詢異常偵測結果

從範例數據源新增數據摘要

Metrics Advisor 支援連接不同類型的資料來源。以下是從 SQL Server 擷取資料的範例。

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const sqlServerConnectionString =
    process.env["METRICS_ADVISOR_SQL_SERVER_CONNECTION_STRING"] ||
    "<connection string to SQL Server>";
  const sqlServerQuery =
    process.env["METRICS_ADVISOR_AZURE_SQL_SERVER_QUERY"] || "<SQL Server query to retrive data>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);

  const created = await createDataFeed(adminClient, sqlServerConnectionString, sqlServerQuery);
  console.log(`Data feed created: ${created.id}`);
}

async function createDataFeed(adminClient, sqlServerConnectionString, sqlServerQuery) {
  console.log("Creating Datafeed...");
  const dataFeed = {
    name: "test_datafeed_" + new Date().getTime().toString(),
    source: {
      dataSourceType: "SqlServer",
      connectionString: sqlServerConnectionString,
      query: sqlServerQuery,
      authenticationType: "Basic"
    },
    granularity: {
      granularityType: "Daily"
    },
    schema: {
      metrics: [
        {
          name: "revenue",
          displayName: "revenue",
          description: "Metric1 description"
        },
        {
          name: "cost",
          displayName: "cost",
          description: "Metric2 description"
        }
      ],
      dimensions: [
        { name: "city", displayName: "city display" },
        { name: "category", displayName: "category display" }
      ],
      timestampColumn: null
    },
    ingestionSettings: {
      ingestionStartTime: new Date(Date.UTC(2020, 5, 1)),
      ingestionStartOffsetInSeconds: 0,
      dataSourceRequestConcurrency: -1,
      ingestionRetryDelayInSeconds: -1,
      stopRetryAfterInSeconds: -1
    },
    rollupSettings: {
      rollupType: "AutoRollup",
      rollupMethod: "Sum",
      rollupIdentificationValue: "__CUSTOM_SUM__"
    },
    missingDataPointFillSettings: {
      fillType: "SmartFilling"
    },
    accessMode: "Private",
    admins: ["xyz@example.com"]
  };
  const result = await adminClient.createDataFeed(dataFeed);

  return result;
}

檢查內嵌狀態

開始進行資料擷取之後，我們可以檢查擷取狀態。

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const dataFeedId = process.env["METRICS_DATAFEED_ID"] || "<data feed id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);
  await checkIngestionStatus(
    adminClient,
    dataFeedId,
    new Date(Date.UTC(2020, 8, 1)),
    new Date(Date.UTC(2020, 8, 12))
  );
}

async function checkIngestionStatus(adminClient, datafeedId, startTime, endTime) {
  // This shows how to use for-await-of syntax to list status
  console.log("Checking ingestion status...");
  const iterator = adminClient.listDataFeedIngestionStatus(datafeedId, startTime, endTime);
  for await (const status of iterator) {
    console.log(`  [${status.timestamp}] ${status.status} - ${status.message}`);
  }
}

設定異常偵測組態

我們需要異常偵測設定，以判斷時間序列中的某個點是否異常。雖然預設偵測設定會自動套用至每個計量，但您可以調整資料所使用的偵測模式，只要建立自訂的異常偵測設定即可。

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const metricId = process.env["METRICS_ADVISOR_METRIC_ID"] || "<metric id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);

  const detectionConfig = await configureAnomalyDetectionConfiguration(adminClient, metricId);
  console.log(`Detection configuration created: ${detectionConfig.id}`);
}

async function configureAnomalyDetectionConfiguration(adminClient, metricId) {
  console.log(`Creating an anomaly detection configuration on metric '${metricId}'...`);
  const anomalyConfig = {
    name: "test_detection_configuration" + new Date().getTime().toString(),
    metricId,
    wholeSeriesDetectionCondition: {
      smartDetectionCondition: {
        sensitivity: 100,
        anomalyDetectorDirection: "Both",
        suppressCondition: {
          minNumber: 1,
          minRatio: 1
        }
      }
    },
    description: "Detection configuration description"
  };
  return await adminClient.createDetectionConfig(anomalyConfig);
}

新增攔截以接收異常警示

我們使用勾點訂閱即時警示。在此範例中，我們會為 Metrics Advisor 服務建立 Webhook，以將警示張貼到該處。

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);
  const hook = await createWebhookHook(adminClient);
  console.log(`Webhook hook created: ${hook.id}`);
}

async function createWebhookHook(adminClient) {
  console.log("Creating a webhook hook");
  const hook = {
    hookType: "Webhook",
    name: "web hook " + new Date().getTime().toString(),
    description: "description",
    hookParameter: {
      endpoint: "https://example.com/handleAlerts",
      username: "username",
      password: "password"
      // certificateKey: "certificate key",
      // certificatePassword: "certificate password"
    }
  };

  return await adminClient.createHook(hook);
}

設定警示組態

然後讓我們設定需要觸發警示的條件，以及要傳送警示的勾點。

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const detectionConfigId = process.env["METRICS_ADVISOR_DETECTION_CONFIG_ID"] || "<detection id>";
  const hookId = process.env["METRICS_ADVISOR_HOOK_ID"] || "<hook id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);
  const alertConfig = await configureAlertConfiguration(adminClient, detectionConfigId, [hookId]);
  console.log(`Alert configuration created: ${alertConfig.id}`);
}

async function configureAlertConfiguration(adminClient, detectionConfigId, hookIds) {
  console.log("Creating a new alerting configuration...");
  const anomalyAlertConfig = {
    name: "test_alert_config_" + new Date().getTime().toString(),
    crossMetricsOperator: "AND",
    metricAlertConfigurations: [
      {
        detectionConfigurationId: detectionConfigId,
        alertScope: {
          scopeType: "All"
        },
        alertConditions: {
          severityCondition: { minAlertSeverity: "Medium", maxAlertSeverity: "High" }
        },
        snoozeCondition: {
          autoSnooze: 0,
          snoozeScope: "Metric",
          onlyForSuccessive: true
        }
      }
    ],
    hookIds,
    description: "Alerting config description"
  };
  return await adminClient.createAlertConfig(anomalyAlertConfig);
}

查詢異常偵測結果

我們可以查詢警示和異常狀況。

const { MetricsAdvisorKeyCredential, MetricsAdvisorClient } = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const alertConfigId = process.env["METRICS_ADVISOR_ALERT_CONFIG_ID"] || "<alert config id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const client = new MetricsAdvisorClient(endpoint, credential);

  const alerts = await queryAlerts(
    client,
    alertConfigId,
    new Date(Date.UTC(2020, 8, 1)),
    new Date(Date.UTC(2020, 8, 12))
  );

  if (alerts.length > 1) {
    // query anomalies using an alert id.
    await queryAnomaliesByAlert(client, alerts[0]);
  } else {
    console.log("No alerts during the time period");
  }
}

async function queryAlerts(client, alertConfigId, startTime, endTime) {
  let alerts = [];
  const iterator = client.listAlerts(alertConfigId, startTime, endTime, "AnomalyTime");
  for await (const alert of iterator) {
    alerts.push(alert);
  }

  return alerts;
}

async function queryAnomaliesByAlert(client, alert) {
  console.log(
    `Listing anomalies for alert configuration '${alert.alertConfigId}' and alert '${alert.id}'`
  );
  const iterator = client.listAnomaliesForAlert(alert);
  for await (const anomaly of iterator) {
    console.log(
      `  Anomaly ${anomaly.severity} ${anomaly.status} ${anomaly.seriesKey} ${anomaly.timestamp}`
    );
  }
}

疑難排解

記錄

啟用記錄有助於找出失敗的相關實用資訊。若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

如需如何啟用記錄的詳細指示，可參閱 @azure/logger 套件文件。

下一步

如需如何使用此連結庫的詳細範例，請參閱範例目錄。

參與

如果您想要參與此文件庫，請閱讀參與指南以深入瞭解如何建置和測試
程序代碼。

Microsoft Azure SDK for Javascript

曝光數

共用方式為

適用於 JavaScript 的 Azure Metrics Advisor 用戶端連結庫 - 1.0.0 版

開始使用

目前支援的環境

必要條件

安裝 `@azure/ai-metrics-advisor` 套件

建立和驗證 `MetricsAdvisorClient` 或 `MetricsAdvisorAdministrationClient`

使用訂用帳戶金鑰和 API 金鑰

使用 Azure 服務目錄

重要概念

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

數據摘要

計量

AnomalyDetectionConfiguration

異常 & 事件

警示

勾點

範例

從範例數據源新增數據摘要

檢查內嵌狀態

設定異常偵測組態

新增攔截以接收異常警示

設定警示組態

查詢異常偵測結果

疑難排解

記錄

下一步

參與

其他資源

共用方式為

適用於 JavaScript 的 Azure Metrics Advisor 用戶端連結庫 - 1.0.0 版

開始使用

目前支援的環境

必要條件

安裝 @azure/ai-metrics-advisor 套件

建立和驗證 MetricsAdvisorClient 或 MetricsAdvisorAdministrationClient

使用訂用帳戶金鑰和 API 金鑰

使用 Azure 服務目錄

重要概念

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

數據摘要

計量

AnomalyDetectionConfiguration

異常 & 事件

警示

勾點

範例

從範例數據源新增數據摘要

檢查內嵌狀態

設定異常偵測組態

新增攔截以接收異常警示

設定警示組態

查詢異常偵測結果

疑難排解

記錄

下一步

參與

相關專案

其他資源

安裝 `@azure/ai-metrics-advisor` 套件

建立和驗證 `MetricsAdvisorClient` 或 `MetricsAdvisorAdministrationClient`