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

适用于 JavaScript 的 Azure 指标顾问客户端库 - 版本 1.0.0

指标顾问是 Azure 认知服务的一部分，使用 AI 对时序数据执行数据监视和异常情况检测。 该服务自动执行将模型应用于数据的过程，并提供了一组 API 和基于 Web 的工作区，用于数据引入、异常检测和诊断，无需了解机器学习即可使用它们。 使用指标顾问执行以下操作：

• 分析来自多个数据源的多维数据
• 识别并关联异常
• 配置并微调用于数据的异常情况检测模型
• 诊断异常，并帮助进行根本原因分析。

关键链接：

• 源代码
• 包 (NPM)
• API 参考文档
• 产品文档
• 示例

入门

目前支持的环境

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

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

先决条件

• 一个 Azure 订阅。
• 现有的 认知服务 或指标顾问资源。 如果需要创建资源，可以使用 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 指标顾问客户端库：

npm install @azure/ai-metrics-advisor

创建和身份验证 MetricsAdvisorClient 或 MetricsAdvisorAdministrationClient

若要创建客户端对象以访问指标顾问 API，需要 endpoint 指标顾问资源的 和 credential。 指标顾问客户端使用指标顾问密钥凭据进行身份验证。

可以在 Azure 门户 或使用以下 Azure CLI 代码片段中找到指标顾问资源的终结点：

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

使用订阅密钥和 API 密钥

需要两个密钥才能对客户端进行身份验证：

• 指标顾问资源的订阅密钥。 可以在 Azure 门户中资源的“密钥和终结点”部分找到此内容。
• 指标顾问实例的 API 密钥。 可以在指标顾问的 Web 门户中左侧导航菜单上的“API 密钥”中找到此密钥。 可以在 Azure 门户中资源的“概述”部分找到 Web 门户的 URL。

使用 Azure 门户 浏览到指标顾问资源并检索订阅密钥，或使用下面的 Azure CLI 代码片段：

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

此外，还需要指标顾问 Web 门户中的每用户 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 应用程序，并通过将“认知服务用户”角色分配给服务主体来授予指标顾问的访问权限 (注意：其他角色（如“所有者”）不会授予必要的权限，只有“认知服务用户”足以运行示例和示例代码) 。

将 AAD 应用程序的客户端 ID、租户 ID 和客户端密码的值设置为环境变量：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET。 我们还支持 Azure Active Directoty 凭据进行身份验证。 需要 Azure 租户 ID、Azure 客户端 ID 和 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 是面向使用指标顾问客户端库的开发人员的主要查询接口。 它提供了用于访问指标顾问特定用途的异步方法，例如列出事件、事件的根本原因、检索原始时序数据和服务扩充的时序数据。

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient 是负责管理指标顾问资源中的实体的接口，例如管理数据馈送、异常情况检测配置、异常警报配置。

数据馈送

数据馈送是指标顾问从数据源（如 Cosmos DB 或 SQL 服务器）中引入的内容。 数据馈送包含以下行：

• 时间戳
• 零个或多个维度
• 一个或多个度量值

指标

指标是一种可量化的度量值，用于监视和评估特定业务流程的状态。 它可以是划分为多个维度的多个时序值的组合。 例如，Web 运行状况指标可能包含用户数和 en-us 市场的维度 。

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration 是每个时序所必需的，并确定时序中的某个点是否为异常。

异常 & 事件

将检测配置应用于指标后， AnomalyIncident每当其中的任何序列具有 时 DataPointAnomaly，都会生成 。

警报

可以配置应触发 的 AnomalyAlert异常。 可以使用不同的设置设置多个警报。 例如，可以针对对业务影响较低的异常创建警报，为更重要的警报创建另一个警报。

挂钩

通过指标顾问，可以创建和订阅实时警报。 这些警报使用通知挂钩通过 Internet 发送。

有关概念的完整列表 ，请参阅指标咨询术语表 文档页。

示例

以下部分提供了几个 JavaScript 代码片段，说明指标顾问客户端库中使用的常见模式。

• 从示例数据源添加数据馈送
• 检查引入状态
• 配置异常情况检测配置
• 添加用于接收异常警报的挂钩
• 配置警报配置
• 查询异常情况检测结果

从示例数据源添加数据馈送

指标顾问支持连接不同类型的数据源。 下面是从 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);
}

添加用于接收异常警报的挂钩

我们使用挂钩订阅实时警报。 在此示例中，我们为指标顾问服务创建一个 Webhook，以将警报 POST 到该服务。

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