JavaScript için Azure Ölçüm Danışmanı istemci kitaplığı - sürüm 1.0.0

  • Makale

Ölçüm Danışmanı, yapay zekanın zaman serisi verilerinde veri izleme ve anomali algılaması gerçekleştirmesini kullanan Azure Bilişsel Hizmetler'in bir parçasıdır. Hizmet, verilerinize model uygulama sürecini otomatikleştirir ve makine öğrenmesini bilmenize gerek kalmadan veri alımı, anomali algılama ve tanılama için bir dizi API web tabanlı çalışma alanı sağlar. Ölçüm Danışmanı'na şu işlemleri yapmak için kullanın:

  • Birden çok veri kaynağından çok boyutlu verileri analiz etme
  • Anomalileri tanımlama ve ilişkilendirme
  • Verilerinizde kullanılan anomali algılama modelini yapılandırma ve hassas ayarlamalar yapma
  • Anomalileri tanılayın ve kök neden analiziyle ilgili yardım alın.

Önemli bağlantılar:

Başlarken

Şu anda desteklenen ortamlar

Daha fazla ayrıntı için destek ilkemize bakın.

Önkoşullar

Azure CLI kullanıyorsanız ve <your-resource-name> yerine kendi benzersiz adlarınızı yazın<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 paketini yükleyin

ile npmJavaScript için Azure Ölçüm Danışmanı istemci kitaplığını yükleyin:

npm install @azure/ai-metrics-advisor

Oluşturma ve kimlik doğrulaması MetricsAdvisorClient veya MetricsAdvisorAdministrationClient

Ölçüm Danışmanı API'sine erişmek üzere bir istemci nesnesi oluşturmak için Ölçüm Danışmanı kaynağınızın ve değerinin credentialolması gerekirendpoint. Ölçüm Danışmanı istemcileri kimlik doğrulaması için Ölçüm Danışmanı anahtar kimlik bilgilerini kullanır.

Ölçüm Danışmanı kaynağınızın uç noktasını Azure Portal'da veya aşağıdaki Azure CLI parçacığını kullanarak bulabilirsiniz:

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

Abonelik Anahtarını ve API Anahtarını Kullanma

İstemcinin kimliğini doğrulamak için iki anahtar gerekir:

  • Ölçüm Danışmanı kaynağınızın abonelik anahtarı. Bunu Azure Portal'daki kaynağınızın Anahtarlar ve Uç Nokta bölümünde bulabilirsiniz.
  • Ölçüm Danışmanı örneğinizin API anahtarı. Bunu Ölçüm Danışmanı web portalında, sol gezinti menüsündeki API tuşları bölümünde bulabilirsiniz. Web portalınızın URL'sini Azure Portal'daki kaynağınızın Genel Bakış bölümünde bulabilirsiniz.

Ölçüm Danışmanı kaynağınıza göz atmak ve bir abonelik anahtarı almak için Azure Portal'ı kullanın veya aşağıdaki Azure CLI parçacığını kullanın:

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

Ayrıca Ölçüm Danışmanı web portalınızdan kullanıcı başına api anahtarına da ihtiyacınız olacaktır.

İki anahtara ve uç noktaya sahip olduktan sonra, istemcilerin kimliğini doğrulamak için sınıfını MetricsAdvisorKeyCredential aşağıdaki gibi kullanabilirsiniz:

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 Service Directory kullanma

API anahtarı yetkilendirmesi örneklerin çoğunda kullanılır, ancak Azure Kimlik kitaplığını kullanarak istemcinin kimliğini Azure Active Directory ile de doğrulayabilirsiniz. Aşağıda gösterilen DefaultAzureCredential sağlayıcısını veya Azure SDK ile sağlanan diğer kimlik bilgileri sağlayıcılarını kullanmak için lütfen paketi yükleyin @azure/identity :

npm install @azure/identity

Hizmet sorumlusu kullanarak kimlik doğrulaması yapmak için bir AAD uygulaması kaydetmeniz ve hizmet sorumlunuza "Bilişsel Hizmetler Kullanıcısı" rolünü atayarak Ölçüm Danışmanı'na erişim vermeniz gerekir (not: "Sahip" gibi diğer roller gerekli izinleri vermez, yalnızca "Bilişsel Hizmetler Kullanıcısı" örnekleri ve örnek kodu çalıştırmak için yeterli olur).

AAD uygulamasının istemci kimliği, kiracı kimliği ve istemci gizli dizisi değerlerini ortam değişkenleri olarak ayarlayın: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET. Azure Active Directoty Kimlik Bilgileri tarafından kimlik doğrulamayı da destekliyoruz. Ortam değişkenleri olarak Azure Kiracı Kimliği, Azure İstemci Kimliği ve Azure İstemci Gizli Anahtarı gerekir.

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);

Önemli kavramlar

MetricsAdvisorClient

MetricsAdvisorClient , Ölçüm Danışmanı istemci kitaplığını kullanan geliştiriciler için birincil sorgulama arabirimidir. Olayları listeleme, olayların kök nedenlerini yeniden deneme, özgün zaman serisi verilerini ve hizmet tarafından zenginleştirilmiş zaman serisi verilerini alma gibi Ölçüm Danışmanı'nın belirli bir kullanımına erişmek için zaman uyumsuz yöntemler sağlar.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient veri akışlarını yönetme, anomali algılama yapılandırmaları, anomali uyarı yapılandırmaları gibi Ölçüm Danışmanı kaynaklarındaki varlıkları yönetmekle sorumlu olan arabirimdir.

Veri Akışı

Veri akışı, Ölçüm Danışmanı'nın Cosmos DB veya SQL sunucusu gibi veri kaynağınızdan alınan veri akışıdır. Veri akışı şu satırları içerir:

  • Zaman damga -ları
  • sıfır veya daha fazla boyut
  • bir veya daha fazla ölçü

Ölçüm

Ölçüm, belirli bir iş sürecinin durumunu izlemek ve değerlendirmek için kullanılan ölçülebilir bir ölçüdür. Boyutlara bölünmüş birden çok zaman serisi değerinin birleşimi olabilir. Örneğin bir web durumu ölçümü, kullanıcı sayısı ve en-us pazarı için boyutlar içerebilir.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration her zaman serisi için gereklidir ve zaman serisindeki bir noktanın anomali olup olmadığını belirler.

Anomali & Olayı

Ölçümlere bir algılama yapılandırması uygulandıktan sonra, AnomalyIncidentiçindeki herhangi bir serinin sahip olduğu DataPointAnomalyher durumda s oluşturulur.

Uyarı

Tetiklenmesi gereken AnomalyAlertanomalileri yapılandırabilirsiniz. Farklı ayarlarla birden çok uyarı ayarlayabilirsiniz. Örneğin, daha düşük iş etkisine sahip anomaliler için bir uyarı ve daha önemli uyarılar için başka bir uyarı oluşturabilirsiniz.

Kan -ca

Ölçüm Danışmanı, gerçek zamanlı uyarılar oluşturmanıza ve bu uyarılara abone olmanıza olanak tanır. Bu uyarılar, bir bildirim kancası kullanılarak İnternet üzerinden gönderilir.

Kavramların kapsamlı bir listesi için lütfen Ölçüm Danışmanlığı Sözlüğü belgeleri sayfasına bakın.

Örnekler

Aşağıdaki bölümde, Ölçüm Danışmanı istemci kitaplıklarında kullanılan yaygın desenleri gösteren çeşitli JavaScript kod parçacıkları sağlanır.

Örnek veri kaynağından veri akışı ekleme

Ölçüm Danışmanı, farklı veri kaynağı türlerinin bağlanmasını destekler. SQL Server'dan veri almak için bir örnek aşağıda verilmiştir.

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;
}

Alma durumunu denetleme

Veri alımını başlattıktan sonra alım durumunu denetleyebiliriz.

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}`);
  }
}

Anomali algılama yapılandırmasını yapılandırma

Zaman serisindeki bir noktanın anomali olup olmadığını belirlemek için anomali algılama yapılandırmasına ihtiyacımız var. Her ölçüme otomatik olarak bir varsayılan algılama yapılandırması uygulanırken, özelleştirilmiş bir anomali algılama yapılandırması oluşturarak verilerinizde kullanılan algılama modlarını ayarlayabilirsiniz.

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);
}

Anomali uyarılarını almak için kanca ekleme

Gerçek zamanlı uyarılara abone oltalarını kullanırız. Bu örnekte, uyarının GÖNDERİP GÖNDERTİĞİ Ölçüm Danışmanı hizmeti için bir web kancası oluşturacağız.

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);
}

Uyarı yapılandırmasını yapılandırma

Ardından bir uyarının hangi koşullarda tetiklenmesi gerektiğini ve uyarının hangi kancalarla gönderileceği yapılandıralım.

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);
}

Sorgu anomali algılama sonuçları

Uyarıları ve anomalileri sorgulayabiliriz.

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}`
    );
  }
}

Sorun giderme

Günlüğe Kaydetme

Günlüğün etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleştirilebilir:

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Sonraki adımlar

Bu kitaplığın nasıl kullanılacağına ilişkin ayrıntılı örnekler için lütfen samples dizinine göz atın.

Katkıda bulunma

Bu kitaplığa katkıda bulunmak isterseniz derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun
koduna bakın.

İzlenimler