.NET 用 Azure Metrics Advisor クライアント ライブラリ - バージョン 1.1.0

Azure Cognitive Services Metrics Advisor は、機械学習を使用して時系列データの異常を監視および検出するクラウド サービスです。 これには、次の機能が含まれています。

• 複数のデータ ソースからの多次元データを分析する。
• 異常を特定して関連付けます。
• データで使用される異常検出モデルを構成して微調整します。
• 異常を診断し、根本原因分析に役立てる

ソースコード | パッケージ (NuGet) | API リファレンス ドキュメント | 製品ドキュメント | サンプル

作業の開始

パッケージをインストールする

NuGet を使用して .NET 用の Azure Metrics Advisor クライアント ライブラリをインストールします。

dotnet add package Azure.AI.MetricsAdvisor

前提条件

• Azure サブスクリプション。
• 既存の Metrics Advisor リソース。

Metrics Advisor リソースを作成する

Metrics Advisor リソースは、次の方法で作成できます。

オプション 1: Azure Portal。

オプション 2: Azure CLI。

CLI を使用して Metrics Advisor リソースを作成する方法の例を次に示します。

# Create a new resource group to hold the Metrics Advisor resource.
# If using an existing resource group, skip this step.
az group create --name <your-resource-name> --location <location>

# Create the Metrics Advisor resource.
az cognitiveservices account create \
    --name <your-resource-name> \
    --resource-group <your-resource-group-name> \
    --kind MetricsAdvisor \
    --sku <sku> \
    --location <location>
    --yes

リソースの作成の詳細、または場所と SKU の情報を取得する方法については、 こちらを参照してください。

クライアントを認証する

Metrics Advisor サービスと対話するには、 クラスまたは クラスの MetricsAdvisorClient インスタンスを作成する MetricsAdvisorAdministrationClient 必要があります。 クライアント オブジェクトをインスタンス化するには、 エンドポイント、 サブスクリプション キー、 API キー が必要です。

エンドポイントとサブスクリプション キーを取得する

エンドポイントとサブスクリプション キーは、 Azure Portal のリソース情報から取得できます。

または、次の Azure CLI スニペットを使用して、Metrics Advisor リソースからサブスクリプション キーを取得することもできます。

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

API キーを取得する

API キーは 、Metrics Advisor Web ポータルで取得できます。 認証のためにログインするように求められます。

ログインしたら、Azure Active Directory、サブスクリプション、メトリック ス アドバイザーのリソース名を入力します。

MetricsAdvisorClient または MetricsAdvisorAdministrationClient を作成する

サブスクリプションキーと API キーを取得したら、 を作成します MetricsAdvisorKeyCredential。 エンドポイントとキー資格情報を使用して、MetricsAdvisorClient を作成できます。

string endpoint = "<endpoint>";
string subscriptionKey = "<subscriptionKey>";
string apiKey = "<apiKey>";
var credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);
var client = new MetricsAdvisorClient(new Uri(endpoint), credential);

また、管理操作を実行するための MetricsAdvisorAdministrationClient を作成することもできます。

string endpoint = "<endpoint>";
string subscriptionKey = "<subscriptionKey>";
string apiKey = "<apiKey>";
var credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);
var adminClient = new MetricsAdvisorAdministrationClient(new Uri(endpoint), credential);

Azure Active Directory を使用して MetricsAdvisorClient または MetricsAdvisorAdministrationClient を作成する

MetricsAdvisorKeyCredential 認証は、このファースト ステップ ガイドの例で使用しますが、Azure Id ライブラリを使用して Azure Active Directory で認証することもできます。

下に示した DefaultAzureCredential プロバイダーか、Azure SDK で提供されている他の資格情報プロバイダーを使用するには、Azure.Identity パッケージをインストールしてください。

Install-Package Azure.Identity

また、新しい AAD アプリケーションを登録し、サービス プリンシパルにロールを"Cognitive Services Metrics Advisor User"割り当てることで Metrics Advisor へのアクセス権を付与する必要があります。 管理者特権が必要な場合は、代わりにロールを割り当てることができます "Cognitive Services Metrics Advisor Administrator" 。

AAD アプリケーションのクライアント ID、テナント ID、クライアント シークレットの値を環境変数として設定します(AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET)。

環境変数を設定したら、 を作成 MetricsAdvisorClientできます。

string endpoint = "<endpoint>";
var client = new MetricsAdvisorClient(new Uri(endpoint), new DefaultAzureCredential());

または、 を作成 MetricsAdvisorAdministrationClient して管理操作を実行することもできます。

string endpoint = "<endpoint>";
var adminClient = new MetricsAdvisorAdministrationClient(new Uri(endpoint), new DefaultAzureCredential());

主要な概念

MetricsAdvisorClient

MetricsAdvisorClient は、Metrics Advisor クライアント ライブラリを使用する開発者向けの主要なクエリ インターフェイスです。 これは、インシデントの一覧表示、インシデントの根本原因の取得、時系列データの取得など、Metrics Advisor の特定の用途にアクセスするための同期メソッドと非同期メソッドを提供します。

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient は、Metrics Advisor リソース内のエンティティの管理を担当するインターフェイスです。 データ フィードの作成と更新、異常検出の構成、異常アラートの構成などのタスクに対して同期および非同期の方法が提供されます。

データ フィード

は DataFeed 、CosmosDB や SQL サーバーなどのデータ ソースから集計データのテーブルを定期的に取り込み、Metrics Advisor サービスで使用できるようにします。 これはデータのエントリ ポイントであるため、異常検出を実行する前に設定する必要がある最初のエージェントです。 詳細については、以下 のデータ ソースからデータ フィードを作成する サンプルを参照してください。

データ フィード メトリック

DataFeedMetric、つまり単に "メトリック" は、特定のビジネス プロセスの状態を評価するために使用される定量化可能なメジャーです。 これは、数か月間の製品のコスト、または温度の毎日の測定値である可能性があります。 サービスは、異常な動作を検索する際に、この値が時間の経過とともにどのように変化するかを監視します。 データ フィードは、同じデータ ソースから複数のメトリックを取り込むことができます。

データ フィード ディメンション

、 DataFeedDimensionつまり単に "ディメンション" は、 メトリックを特徴付けるカテゴリ値です。 たとえば、メトリックが製品のコストを表す場合、製品の種類 (靴、帽子など) と、これらの値が測定された都市 (ニューヨーク、東京など) をディメンションとして使用できます。 複数のディメンションの組み合わせによって、特定の一変量時系列が識別 されます。

タイム シリーズ

時系列は、時系列でインデックス付けされたデータ ポイントのシーケンスです。 これらのデータ ポイントは、時間の経過に伴う メトリック の値の変動を表します。

メトリックを指定すると、Metrics Advisor サービスは 、ディメンション 値の可能な組み合わせごとに 1 つの系列を作成します。つまり、同じメトリックに対して複数の時系列を監視できます。

たとえば、次のデータ列がデータ ソースによって返されるとします。

City	カテゴリ	コスト	収益
ニューヨーク	靴	1045.00	1345.00
ニューヨーク	帽子	670.00	502.00
デリー	靴	991.00	1009.00
デリー	帽子	623.00	711.00

コストと収益はサービスで監視するメトリックですが、市区町村とカテゴリはそれらのメトリックを特徴付けるディメンションです。 このデータには、次の 4 つのディメンションの組み合わせが考えられます。

• 市区町村 = ニューヨーク、 カテゴリ = 靴
• City = New York、Category = Hats
• City = デリー、カテゴリ = 靴
• City = Delhi、Category = Hats

メトリックごとに、サービスは 4 つの時系列を作成してデータを監視します。各時系列は、1 つの可能なディメンションの組み合わせを表します。 データ ソースの取り込みが行われるたびに、新しく取り込まれたデータで使用可能な場合、これらの系列は新しいデータ ポイントで更新されます。

データ ポイントの異常

または DataPointAnomaly単に "異常" は、 時系列 内のデータ ポイントが予期せず動作したときに発生します。 データ ポイントの値が大きすぎる場合や低すぎる場合、または近いポイントの間でその値が突然変化した場合に発生する可能性があります。 を使用して異常と見なされるように、データ ポイントが満たす必要がある条件を AnomalyDetectionConfiguration指定できます。 データ インジェストが行われると、サービスは、異常を検索する新しいポイントのセットに既存のすべての構成を適用します。 詳細については、以下 の「異常検出構成の作成 」のサンプルを参照してください。

異常インシデント

特定のタイムスタンプで 1 つのメトリック内の複数の時系列で異常が検出された場合、Metrics Advisor サービスは、同じ根本原因を共有する異常を 1 つの AnomalyIncident、または単に "インシデント" に自動的にグループ化します。 これにより、個々の異常をチェックする作業が大幅に削除され、問題の最も重要な要因をすばやく見つけることができます。

異常アラート

、 AnomalyAlertまたは単に "アラート" は、検出された 異常 が指定された条件を満たしたときにトリガーされます。 たとえば、重大度が高い異常が検出されるたびにアラートをトリガーできます。 を使用してアラートをトリガーするために異常が満たす必要がある条件を AnomalyAlertConfiguration指定できます。 新しく取り込まれたデータ ポイントに対して異常検出が実行されると、サービスは既存のすべての構成を新しい異常に適用し、各構成は、指定された条件を満たすポイントのセットに対して 1 つのアラートを発生させます。 アラートの構成は既定では設定されないため、アラートのトリガーを開始するにはアラートを作成する必要があります。 詳細については、以下 の「異常アラート構成の作成 」のサンプルを参照してください。

通知フック

NotificationHook、または単に "フック" は、アラート通知をサブスクライブする手段です。 フックを に AnomalyAlertConfiguration 渡し、作成するすべてのアラートの通知の取得を開始できます。 詳細については、以下 の「異常アラートを受信するためのフックを作成する 」のサンプルを参照してください。

スレッド セーフ

すべてのクライアント インスタンス メソッドがスレッド セーフであり、相互に独立していることを保証します (ガイドライン)。 これにより、スレッド間であっても、クライアント インスタンスの再利用に関する推奨事項が常に安全になります。

その他の概念

クライアント オプション | 応答 | へのアクセスエラーの | 処理診断 | あざける | クライアントの有効期間

例

次のセクションでは、Metrics Advisor .NET API で使用される一般的なパターンを示すコード スニペットをいくつか示します。 以下のスニペットでは非同期サービス呼び出しを利用していますが、Azure.AI.MetricsAdvisor パッケージでは同期 API と非同期 API の両方がサポートされていることに注意してください。

• データ ソースからデータ フィードを作成する
• その他のデータ ソース認証の代替手段
• データ フィードのインジェスト状態を確認する
• 異常検出構成を作成する
• 異常アラートを受信するためのフックを作成する
• 異常アラート構成を作成する
• 検出された異常とトリガーされたアラートのクエリ

データ ソースからデータ フィードを作成する

Metrics Advisor では、複数の種類のデータ ソースがサポートされています。 このサンプルでは、SQL Server からデータを抽出する DataFeed を作成する方法を示します。

string sqlServerConnectionString = "<connectionString>";
string sqlServerQuery = "<query>";

var dataFeed = new DataFeed();

dataFeed.Name = "<dataFeedName>";
dataFeed.DataSource = new SqlServerDataFeedSource(sqlServerConnectionString, sqlServerQuery);
dataFeed.Granularity = new DataFeedGranularity(DataFeedGranularityType.Daily);

dataFeed.Schema = new DataFeedSchema();
dataFeed.Schema.MetricColumns.Add(new DataFeedMetric("cost"));
dataFeed.Schema.MetricColumns.Add(new DataFeedMetric("revenue"));
dataFeed.Schema.DimensionColumns.Add(new DataFeedDimension("category"));
dataFeed.Schema.DimensionColumns.Add(new DataFeedDimension("city"));

dataFeed.IngestionSettings = new DataFeedIngestionSettings(DateTimeOffset.Parse("2020-01-01T00:00:00Z"));

Response<DataFeed> response = await adminClient.CreateDataFeedAsync(dataFeed);

DataFeed createdDataFeed = response.Value;

Console.WriteLine($"Data feed ID: {createdDataFeed.Id}");
Console.WriteLine($"Data feed status: {createdDataFeed.Status.Value}");
Console.WriteLine($"Data feed created time: {createdDataFeed.CreatedOn.Value}");

Console.WriteLine($"Data feed administrators:");
foreach (string admin in createdDataFeed.Administrators)
{
    Console.WriteLine($" - {admin}");
}

Console.WriteLine($"Metric IDs:");
foreach (DataFeedMetric metric in createdDataFeed.Schema.MetricColumns)
{
    Console.WriteLine($" - {metric.Name}: {metric.Id}");
}

Console.WriteLine($"Dimensions:");
foreach (DataFeedDimension dimension in createdDataFeed.Schema.DimensionColumns)
{
    Console.WriteLine($" - {dimension.Name}");
}

その他のデータ ソース認証の代替手段

一部のデータ ソースでは、複数の種類の認証がサポートされています。 たとえば、 は SqlServerDataFeedSource 接続文字列、サービス プリンシパル、マネージド ID をサポートしています。 データ ソースとその認証の種類の完全な一覧については、こちらをチェック。

使用する認証がデータ ソースでサポートされていることを確認したら、データ ソースを作成または更新するときに プロパティを設定 Authentication する必要があります。

var dataSoure = new SqlServerDataFeedSource("<connection-string>", "<query>")
{
    Authentication = SqlServerDataFeedSource.AuthenticationType.ManagedIdentity
};

認証の 種類と ManagedIdentity の種類を除きBasic、サービス内の対応する DataSourceCredentialEntity の ID も必要であることに注意してください。 資格情報エンティティを作成するには、次の操作を行う必要があります。

string credentialName = "<credentialName>";

var credentialEntity = new ServicePrincipalCredentialEntity(credentialName, "<clientId>", "<clientSecret>", "<tenantId>");

Response<DataSourceCredentialEntity> response = await adminClient.CreateDataSourceCredentialAsync(credentialEntity);

DataSourceCredentialEntity createdCredentialEntity = response.Value;

Console.WriteLine($"Credential entity ID: {createdCredentialEntity.Id}");

ID を取得したら、データ ソースを DataSourceCredentialId 設定するときにプロパティに追加します。

var dataSoure = new SqlServerDataFeedSource("<connection-string>", "<query>")
{
    Authentication = SqlServerDataFeedSource.AuthenticationType.ServicePrincipal,
    DataSourceCredentialId = "<credentialId>"
};

データ フィードのインジェスト状態を確認する

以前に作成 DataFeedした のインジェスト状態を確認します。

string dataFeedId = "<dataFeedId>";

var startsOn = DateTimeOffset.Parse("2020-01-01T00:00:00Z");
var endsOn = DateTimeOffset.Parse("2020-09-09T00:00:00Z");
var options = new GetDataFeedIngestionStatusesOptions(startsOn, endsOn)
{
    MaxPageSize = 5
};

Console.WriteLine("Ingestion statuses:");
Console.WriteLine();

int statusCount = 0;

await foreach (DataFeedIngestionStatus ingestionStatus in adminClient.GetDataFeedIngestionStatusesAsync(dataFeedId, options))
{
    Console.WriteLine($"Timestamp: {ingestionStatus.Timestamp}");
    Console.WriteLine($"Status: {ingestionStatus.Status}");
    Console.WriteLine($"Service message: {ingestionStatus.Message}");
    Console.WriteLine();

    // Print at most 5 statuses.
    if (++statusCount >= 5)
    {
        break;
    }
}

異常検出構成を作成する

AnomalyDetectionConfigurationを作成して、異常と見なされるデータ ポイントをサービスに指示します。

string metricId = "<metricId>";
string configurationName = "<configurationName>";

var detectionConfiguration = new AnomalyDetectionConfiguration()
{
    MetricId = metricId,
    Name = configurationName,
    WholeSeriesDetectionConditions = new MetricWholeSeriesDetectionCondition()
};

var detectCondition = detectionConfiguration.WholeSeriesDetectionConditions;

var hardSuppress = new SuppressCondition(1, 100);
detectCondition.HardThresholdCondition = new HardThresholdCondition(AnomalyDetectorDirection.Down, hardSuppress)
{
    LowerBound = 5.0
};

var smartSuppress = new SuppressCondition(4, 50);
detectCondition.SmartDetectionCondition = new SmartDetectionCondition(10.0, AnomalyDetectorDirection.Up, smartSuppress);

detectCondition.ConditionOperator = DetectionConditionOperator.Or;

Response<AnomalyDetectionConfiguration> response = await adminClient.CreateDetectionConfigurationAsync(detectionConfiguration);

AnomalyDetectionConfiguration createdDetectionConfiguration = response.Value;

Console.WriteLine($"Anomaly detection configuration ID: {createdDetectionConfiguration.Id}");

異常アラートを受信するためのフックを作成する

Metrics Advisor では、EmailNotificationHookアラート通知をWebNotificationHookサブスクライブする手段として、 クラスと クラスがサポートされています。 この例では、EmailNotificationHook を作成する方法を示します。 通知の取得を開始するには、フックを異常アラート構成に渡す必要があることに注意してください。 詳細については、以下 の「異常アラート構成の作成 」のサンプルを参照してください。

string hookName = "<hookName>";

var emailHook = new EmailNotificationHook(hookName);

emailHook.EmailsToAlert.Add("email1@sample.com");
emailHook.EmailsToAlert.Add("email2@sample.com");

Response<NotificationHook> response = await adminClient.CreateHookAsync(emailHook);

NotificationHook createdHook = response.Value;

Console.WriteLine($"Hook ID: {createdHook.Id}");

異常アラート構成を作成する

AnomalyAlertConfiguration を作成して、どの異常によってアラートがトリガーされるべきかをサービスに伝え ます。

string hookId = "<hookId>";
string anomalyDetectionConfigurationId = "<anomalyDetectionConfigurationId>";
string configurationName = "<configurationName>";

AnomalyAlertConfiguration alertConfiguration = new AnomalyAlertConfiguration()
{
    Name = configurationName
};

alertConfiguration.IdsOfHooksToAlert.Add(hookId);

var scope = MetricAnomalyAlertScope.CreateScopeForWholeSeries();
var metricAlertConfiguration = new MetricAlertConfiguration(anomalyDetectionConfigurationId, scope);

alertConfiguration.MetricAlertConfigurations.Add(metricAlertConfiguration);

Response<AnomalyAlertConfiguration> response = await adminClient.CreateAlertConfigurationAsync(alertConfiguration);

AnomalyAlertConfiguration createdAlertConfiguration = response.Value;

Console.WriteLine($"Alert configuration ID: {createdAlertConfiguration.Id}");

検出された異常とトリガーされたアラートのクエリ

特定の異常 アラート 構成によって作成されたアラートを確認します。

string anomalyAlertConfigurationId = "<anomalyAlertConfigurationId>";

var startsOn = DateTimeOffset.Parse("2020-01-01T00:00:00Z");
var endsOn = DateTimeOffset.UtcNow;
var options = new GetAlertsOptions(startsOn, endsOn, AlertQueryTimeMode.AnomalyDetectedOn)
{
    MaxPageSize = 5
};

int alertCount = 0;

await foreach (AnomalyAlert alert in client.GetAlertsAsync(anomalyAlertConfigurationId, options))
{
    Console.WriteLine($"Alert created at: {alert.CreatedOn}");
    Console.WriteLine($"Alert at timestamp: {alert.Timestamp}");
    Console.WriteLine($"Id: {alert.Id}");
    Console.WriteLine();

    // Print at most 5 alerts.
    if (++alertCount >= 5)
    {
        break;
    }
}

アラートの ID がわかったら、このアラートをトリガーした異常を一覧表示します。

string alertConfigurationId = "<alertConfigurationId>";
string alertId = "<alertId>";

var options = new GetAnomaliesForAlertOptions() { MaxPageSize = 3 };

int anomalyCount = 0;

await foreach (DataPointAnomaly anomaly in client.GetAnomaliesForAlertAsync(alertConfigurationId, alertId, options))
{
    Console.WriteLine($"Anomaly detection configuration ID: {anomaly.DetectionConfigurationId}");
    Console.WriteLine($"Data feed ID: {anomaly.DataFeedId}");
    Console.WriteLine($"Metric ID: {anomaly.MetricId}");
    Console.WriteLine($"Anomaly value: {anomaly.Value}");

    if (anomaly.ExpectedValue.HasValue)
    {
        Console.WriteLine($"Anomaly expected value: {anomaly.ExpectedValue}");
    }

    Console.WriteLine($"Anomaly at timestamp: {anomaly.Timestamp}");
    Console.WriteLine($"Anomaly detected at: {anomaly.CreatedOn}");
    Console.WriteLine($"Status: {anomaly.Status}");
    Console.WriteLine($"Severity: {anomaly.Severity}");
    Console.WriteLine("Series key:");

    foreach (KeyValuePair<string, string> dimension in anomaly.SeriesKey)
    {
        Console.WriteLine($"  Dimension '{dimension.Key}': {dimension.Value}");
    }

    Console.WriteLine();

    // Print at most 3 anomalies.
    if (++anomalyCount >= 3)
    {
        break;
    }
}

トラブルシューティング

全般

.NET SDK を使用して Cognitive Services Metrics Advisor クライアント ライブラリを操作すると、サービスによって返されるエラーにより RequestFailedException 、 REST API 要求によって返されたのと同じ HTTP 状態コードが返されます。

たとえば、存在しない ID を持つデータ フィードをサービスから取得しようとすると、 404 "Not Found" を示すエラーが返されます。

string dataFeedId = "00000000-0000-0000-0000-000000000000";

try
{
    Response<DataFeed> response = await adminClient.GetDataFeedAsync(dataFeedId);
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

サービスによって返されるエラー メッセージなど、追加情報がログに記録されることに注意してください。

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"code":"ERROR_INVALID_PARAMETER","message":"datafeedId is invalid."}

Headers:
X-Request-ID: REDACTED
x-envoy-upstream-service-time: REDACTED
apim-request-id: REDACTED
Strict-Transport-Security: REDACTED
X-Content-Type-Options: REDACTED
Date: Thu, 08 Oct 2020 09:04:31 GMT
Content-Length: 69
Content-Type: application/json; charset=utf-8

コンソール ログの設定

ログを表示する最も簡単な方法は、コンソールログを有効にすることです。

コンソールにメッセージを出力する Azure SDK ログ リスナーを作成するには、 メソッドを AzureEventSourceListener.CreateConsoleLogger 使用します。

// Set up a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

その他のログメカニズムの詳細については、「 診断サンプル」を参照してください。

次のステップ

Cognitive Services Metrics Advisor ライブラリの使用方法を示すサンプルは、この GitHub リポジトリで入手できます。 メイン機能領域ごとにサンプルが提供されます。

• データ フィード CRUD 操作
• 資格情報エンティティ CRUD 操作
• データ フィードインジェスト操作
• 異常検出構成 CRUD 操作
• フック CRUD 操作
• 異常アラート構成 CRUD 操作
• トリガーされたアラートのクエリ
• 検出された異常のクエリ
• インシデントとその根本原因を照会する
• 時系列情報のクエリ
• フィードバック CRUD 操作

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。