クイックスタート:Anomaly Detector クライアントライブラリによる異常検出 - Azure AI services

Library リファレンスドキュメントLibrary ソースコードPackage (NuGet) GitHub

C# 用 Anomaly Detector クライアントライブラリを使ってみます。サービスによって提供されるアルゴリズムを使用してパッケージをインストールするには、次の手順に従います。 Anomaly Detector サービスにより、業界、シナリオ、データ量に関係なく、最適なモデルを自動的に使用することで、時系列データ内の異常を検出できます。

.C# 用 Anomaly Detector クライアントライブラリは次の目的で使用します。

バッチ要求として、時系列データセット全体で異常を検出する
時系列で最新のデータポイントの異常状態を検出する
データセット内の傾向変化点を検出する。

前提条件

Azure サブスクリプション - 無料で作成します
現在のバージョンの .NET Core
Azure サブスクリプションを取得したら、Azure ポータルに Anomaly Detector リソースを作成して、キーとエンドポイントを取得します。デプロイされるまで待ち、 [リソースに移動] ボタンを選択します。 Free 価格レベル (F0) を使用してサービスを試用し、後から運用環境用の有料レベルにアップグレードすることができます。

セットアップ

新しい .NET Core アプリケーションを作成する

コンソールウィンドウ (cmd、PowerShell、Bash など) で、dotnet new コマンドを使用し、anomaly-detector-quickstart という名前で新しいコンソールアプリを作成します。このコマンドは、単一の C# ソースファイル (Program.cs を使用して、単純な "Hello World" プロジェクトを作成します。

dotnet new console -n anomaly-detector-quickstart

新しく作成されたアプリフォルダーにディレクトリを変更します。次を使用してアプリケーションをビルドできます。

dotnet build

ビルドの出力に警告やエラーが含まれないようにする必要があります。

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

クライアントライブラリをインストールする

アプリケーションディレクトリ内で、次のコマンドを使用して、.NET用の Anomaly Detector クライアントライブラリをインストールします。

dotnet add package Azure.AI.AnomalyDetector --prerelease

キーとエンドポイントを取得する

Anomaly Detector サービスに対する呼び出しを正しく行うには、次の値が必要です。

変数名	値
`ANOMALY_DETECTOR_ENDPOINT`	Azure ポータルでリソースを確認する際は、「Keys とエンドポイント」セクションにこの値があります。エンドポイントの例: `https://YOUR_RESOURCE_NAME.cognitiveservices.azure.com/`
`ANOMALY_DETECTOR_API_KEY`	API キーの値は、Azure ポータルでリソースを調べる時のキーとエンドポイントセクションにあります。 `KEY1` または `KEY2` を使用できます。
`DATA_PATH`	このクイックスタートでは、`request-data.csv`からダウンロードできるファイルを使用します。例のパス: `c:\\test\\request-data.csv`

Azure ポータルでリソースに移動します。 [エンドポイントとキー] は [リソース管理] セクションにあります。エンドポイントとアクセスキーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1 または KEY2 を使用できます。常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。

環境変数を作成する

キーとエンドポイントの永続的な環境変数を作成して割り当てます。

重要

クラウドで実行されるアプリケーションに資格情報を格納しないように、 Azure リソースの管理された ID を使用して認証をMicrosoft Entra IDすることをお勧めします。

API キーは慎重に使用してください。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。 API キーを使用する場合は、Azure Key Vaultに安全に格納し、キーを定期的にローテーションし、ロールベースのアクセス制御とネットワークアクセス制限を使用してAzure Key Vaultへのアクセスを制限します。アプリで API キーを安全に使用する方法の詳細については、「Azure Key Vault を使用した API キー」を参照してください。

AI サービスのセキュリティの詳細については、「Authenticate requests to Azure AI サービス」を参照してください。

setx ANOMALY_DETECTOR_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

setx ANOMALY_DETECTOR_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

[System.Environment]::SetEnvironmentVariable('ANOMALY_DETECTOR_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')

[System.Environment]::SetEnvironmentVariable('ANOMALY_DETECTOR_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

echo export ANOMALY_DETECTOR_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE" >> /etc/environment && source /etc/environment

echo export ANOMALY_DETECTOR_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE" >> /etc/environment && source /etc/environment

サンプルデータをダウンロードする

このクイックスタートでは、request-data.csv ファイルを、GitHub のサンプルデータからダウンロードして使用します。

次を実行してサンプルデータをダウンロードすることもできます。

curl "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/anomalydetector/azure-ai-anomalydetector/samples/sample_data/request-data.csv" --output request-data.csv

異常を検出する

プロジェクトディレクトリから program.cs ファイルを開いて、以下のコードに置き換えます。

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using Azure;
using Azure.AI.AnomalyDetector;
using static System.Environment;

namespace anomaly_detector_quickstart
{
    internal class Program
    {
        static void Main(string[] args)
        {
            string endpoint = GetEnvironmentVariable("ANOMALY_DETECTOR_ENDPOINT");
            string apiKey = GetEnvironmentVariable("ANOMALY_DETECTOR_API_KEY");

            var endpointUri = new Uri(endpoint);
            var credential = new AzureKeyCredential(apiKey);

            //create client
            AnomalyDetectorClient client = new AnomalyDetectorClient(endpointUri, credential);

            //read data
            //example: string datapath = @"c:\test\request-data.csv";
            string datapath = @"REPLACE_WITH_YOUR_LOCAL_SAMPLE_REQUEST_DATA_PATH";

            List<TimeSeriesPoint> list = File.ReadAllLines(datapath, Encoding.UTF8)
                .Where(e => e.Trim().Length != 0)
                .Select(e => e.Split(','))
                .Where(e => e.Length == 2)
                .Select(e => new TimeSeriesPoint(float.Parse(e[1])) { Timestamp = DateTime.Parse(e[0]) }).ToList();

              //create request
            UnivariateDetectionOptions request = new UnivariateDetectionOptions(list)
            {
                Granularity = TimeGranularity.Daily
            };

            UnivariateEntireDetectionResult result = client.DetectUnivariateEntireSeries(request);

            bool hasAnomaly = false;
            for (int i = 0; i < request.Series.Count; ++i)
            {
                if (result.IsAnomaly[i])
                {
                    Console.WriteLine("Anomaly detected at index: {0}.", i);
                    hasAnomaly = true;
                }
            }
            if (!hasAnomaly)
            {
                Console.WriteLine("No anomalies detected in the series.");
            }
        }
    }
}

次のコマンドでアプリケーションを実行します。

dotnet run program.cs

出力

Anomaly detected at index:      3
Anomaly detected at index:      18
Anomaly detected at index:      21
Anomaly detected at index:      22
Anomaly detected at index:      23
Anomaly detected at index:      24
Anomaly detected at index:      25
Anomaly detected at index:      28
Anomaly detected at index:      29
Anomaly detected at index:      30
Anomaly detected at index:      31
Anomaly detected at index:      32
Anomaly detected at index:      35
Anomaly detected at index:      44

コードの詳細

結果を理解する

上記のコードでは、サンプルデータが読み取られて、DetectRequest オブジェクトに変換されます。ファイルパスを指定して File.ReadAllLines を呼び出し、TimeSeriesPoint オブジェクトのリストを作成して、改行文字をすべて削除します。値を抽出し、その数値からタイムスタンプを分離して、それらを新しい TimeSeriesPoint オブジェクトに追加します。 DetectRequest オブジェクトは一連のデータポイントで構成されており、データポイントの細分性 (つまり周期性) は TimeGranularity.Daily です。次に、DetectEntireSeriesAsync オブジェクトを使ってクライアントの DetectRequest メソッドを呼び出し、EntireDetectResponse オブジェクトとしての応答を待機します。次に、応答の IsAnomaly の値を反復処理し、true であるものをすべて出力します。これらの値は、異常なデータポイントが見つかった場合、そのインデックスに対応します。

リソースをクリーンアップする

Anomaly Detector リソースをクリーンアップして削除したい場合は、リソースまたはリソースグループを削除できます。リソースグループを削除すると、それに関連付けられている他のリソースも削除されます。また、作成した環境変数を使用しない場合は、それらの削除を検討することもできます。

Library リファレンスドキュメントLibrary ソースコードPackage (npm)サンプルコードを GitHub

JavaScript 用 Anomaly Detector クライアントライブラリを使ってみます。これらの手順に従ってパッケージをインストールすれば、サービスによって提供されるアルゴリズムが使用できるようになります。 Anomaly Detector サービスにより、業界、シナリオ、データ量に関係なく、最適なモデルを自動的に使用することで、時系列データ内の異常を検出できます。

JavaScript 用 Anomaly Detector クライアントライブラリは、次の目的で使用することができます。

バッチ要求として、時系列データセット全体で異常を検出する
時系列で最新のデータポイントの異常状態を検出する
データセット内の傾向変化点を検出する。

前提条件

Azure サブスクリプション - 無料で作成します
最新バージョンの Node.js
Azure サブスクリプションを取得したら、Azure ポータルに Anomaly Detector リソースを作成して、キーとエンドポイントを取得します。デプロイされるまで待ち、 [リソースに移動] ボタンを選択します。 Free 価格レベル (F0) を使用してサービスを試用し、後から運用環境用の有料レベルにアップグレードすることができます。

セットアップ

新しい Node.js アプリケーションを作成する

コンソールウィンドウ (cmd、PowerShell、Bash など) で、ご利用のアプリ用に新しいディレクトリを作成し、そこに移動します。

mkdir myapp && cd myapp

次の内容を持つ新しいファイル package.json を作成します。

{
  "dependencies": {
    "@azure/ai-anomaly-detector": "next",
    "@azure-rest/ai-anomaly-detector": "next",
    "@azure/core-auth": "^1.3.0",
    "csv-parse": "^5.3.0"
  }
}

クライアントライブラリをインストールする

package.json ファイルと同じディレクトリから次のように実行して、必要な npm パッケージをインストールします。

npm install

キーとエンドポイントを取得する

Anomaly Detector サービスに対する呼び出しを正しく行うには、次の値が必要です。

変数名	値
`ANOMALY_DETECTOR_ENDPOINT`	Azure ポータルでリソースを確認する際は、「Keys とエンドポイント」セクションにこの値があります。エンドポイントの例: `https://YOUR_RESOURCE_NAME.cognitiveservices.azure.com/`
`ANOMALY_DETECTOR_API_KEY`	API キーの値は、Azure ポータルでリソースを調べる時のキーとエンドポイントセクションにあります。 `KEY1` または `KEY2` を使用できます。
`datapath`	このクイックスタートでは、`request-data.csv`からダウンロードできるファイルを使用します。

Azure ポータルでリソースに移動します。 [エンドポイントとキー] は [リソース管理] セクションにあります。エンドポイントとアクセスキーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1 または KEY2 を使用できます。常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。

環境変数を作成する

キーとエンドポイントの永続的な環境変数を作成して割り当てます。

重要

クラウドで実行されるアプリケーションに資格情報を格納しないように、 Azure リソースの管理された ID を使用して認証をMicrosoft Entra IDすることをお勧めします。

API キーは慎重に使用してください。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。 API キーを使用する場合は、Azure Key Vaultに安全に格納し、キーを定期的にローテーションし、ロールベースのアクセス制御とネットワークアクセス制限を使用してAzure Key Vaultへのアクセスを制限します。アプリで API キーを安全に使用する方法の詳細については、「Azure Key Vault を使用した API キー」を参照してください。

AI サービスのセキュリティの詳細については、「Authenticate requests to Azure AI サービス」を参照してください。

setx ANOMALY_DETECTOR_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

setx ANOMALY_DETECTOR_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

[System.Environment]::SetEnvironmentVariable('ANOMALY_DETECTOR_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')

[System.Environment]::SetEnvironmentVariable('ANOMALY_DETECTOR_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

echo export ANOMALY_DETECTOR_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE" >> /etc/environment && source /etc/environment

echo export ANOMALY_DETECTOR_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE" >> /etc/environment && source /etc/environment

サンプルデータをダウンロードする

このクイックスタートでは、request-data.csv ファイルを、GitHub のサンプルデータからダウンロードして使用します。

次を実行してサンプルデータをダウンロードすることもできます。

curl "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/anomalydetector/azure-ai-anomalydetector/samples/sample_data/request-data.csv" --output request-data.csv

異常を検出する

index.js という名前のファイルを作成し、次のコードに置き換えます。

const AnomalyDetector = require("@azure-rest/ai-anomaly-detector").default,
  { isUnexpected } = require("@azure-rest/ai-anomaly-detector");
const { AzureKeyCredential } = require("@azure/core-auth");

const { parse } = require("csv-parse/sync");
const fs = require("fs");

// Retrieve the endpoint and key from the environment variables.
const apiKey = process.env["ANOMALY_DETECTOR_API_KEY"] || "";
const endpoint = process.env["ANOMALY_DETECTOR_ENDPOINT"] || "";
const timeSeriesDataPath = "./request-data.csv";

function read_series_from_file(path) {
  let result = Array();
  let input = fs.readFileSync(path).toString();
  let parsed = parse(input, { skip_empty_lines: true });
  parsed.forEach(function (e) {
    result.push({ timestamp: new Date(e[0]), value: Number(e[1]) });
  });
  return result;
}

async function main() {
  // create client
  const credential = new AzureKeyCredential(apiKey);
  const client = AnomalyDetector(endpoint, credential);

  // construct request
  const options = {
    body: {
      granularity: "daily",
      imputeMode: "auto",
      maxAnomalyRatio: 0.25,
      sensitivity: 95,
      series: read_series_from_file(timeSeriesDataPath),
    },
    headers: { "Content-Type": "application/json" },
  };

  // get last detect result
  const result = await client.path("/timeseries/entire/detect").post(options);
  if (isUnexpected(result)) {
    throw result;
  }

  if (result.body.isAnomaly) {
    result.body.isAnomaly.forEach(function (anomaly, index) {
      if (anomaly === true) {
        console.log(index);
      }
    });
  } else {
    console.log("There is no anomaly detected from the series.");
  }

}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

module.exports = { main };

アプリケーションの実行

クイックスタートファイルで node コマンドを使用して、アプリケーションを実行します。

node index.js

出力

Anomalies were detected from the series at index:
3
18
21
22
23
24
25
28
29
30
31
32
35
44

結果を理解する

上記のコードでは、Azure AI Anomaly Detectorを呼び出して、クライアントの detectEntireSeries() メソッドを使用して、時系列全体の異常をバッチとして検出します。返された AnomalyDetectorDetectEntireSeriesResponse オブジェクトを格納します。次に、応答の isAnomaly リストを反復処理して、すべての true 値のインデックスを出力します。これらの値は、異常なデータポイントが見つかった場合、そのインデックスに対応します。

リソースをクリーンアップする

Anomaly Detector リソースをクリーンアップして削除したい場合は、リソースまたはリソースグループを削除できます。リソースグループを削除すると、それに関連付けられている他のリソースも削除されます。また、作成した環境変数を使用しない場合は、それらの削除を検討することもできます。

Library リファレンスドキュメントLibrary ソースコードPackage (PyPi) GitHub

Python用 Anomaly Detector クライアントライブラリの使用を開始します。これらの手順に従ってパッケージをインストールすれば、サービスによって提供されるアルゴリズムが使用できるようになります。 Anomaly Detector サービスにより、業界、シナリオ、データ量に関係なく、最適なモデルを自動的に使用することで、時系列データ内の異常を検出できます。

Anomaly Detector クライアントライブラリを使用して、Pythonで以下を行います。

バッチ要求として、時系列データセット全体で異常を検出する
時系列で最新のデータポイントの異常状態を検出する
データセット内の傾向変化点を検出する。

前提条件

Azure サブスクリプション - 無料で作成します
Python 3.x
Pandas データ分析ライブラリ
Azure サブスクリプションを取得したら、Azure ポータルに Anomaly Detector リソースを作成して、キーとエンドポイントを取得します。デプロイされるまで待ち、 [リソースに移動] ボタンを選択します。 Free 価格レベル (F0) を使用してサービスを試用し、後から運用環境用の有料レベルにアップグレードすることができます。

セットアップ

クライアントライブラリをインストールします。次のようにして、クライアントライブラリをインストールできます。

pip install --upgrade azure.ai.anomalydetector

キーとエンドポイントを取得する

Anomaly Detector サービスに対する呼び出しを正しく行うには、次の値が必要です。

変数名	値
`ANOMALY_DETECTOR_ENDPOINT`	Azure ポータルでリソースを確認する際は、「Keys とエンドポイント」セクションにこの値があります。エンドポイントの例: `https://YOUR_RESOURCE_NAME.cognitiveservices.azure.com/`
`ANOMALY_DETECTOR_API_KEY`	API キーの値は、Azure ポータルでリソースを調べる時のキーとエンドポイントセクションにあります。 `KEY1` または `KEY2` を使用できます。
`DATA_PATH`	このクイックスタートでは、`request-data.csv`からダウンロードできるファイルを使用します。例のパス: `c:\\test\\request-data.csv`

Azure ポータルでリソースに移動します。 [エンドポイントとキー] は [リソース管理] セクションにあります。エンドポイントとアクセスキーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1 または KEY2 を使用できます。常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。

環境変数を作成する

キーとエンドポイントの永続的な環境変数を作成して割り当てます。

重要

クラウドで実行されるアプリケーションに資格情報を格納しないように、 Azure リソースの管理された ID を使用して認証をMicrosoft Entra IDすることをお勧めします。

API キーは慎重に使用してください。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。 API キーを使用する場合は、Azure Key Vaultに安全に格納し、キーを定期的にローテーションし、ロールベースのアクセス制御とネットワークアクセス制限を使用してAzure Key Vaultへのアクセスを制限します。アプリで API キーを安全に使用する方法の詳細については、「Azure Key Vault を使用した API キー」を参照してください。

AI サービスのセキュリティの詳細については、「Authenticate requests to Azure AI サービス」を参照してください。

setx ANOMALY_DETECTOR_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

setx ANOMALY_DETECTOR_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

[System.Environment]::SetEnvironmentVariable('ANOMALY_DETECTOR_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')

[System.Environment]::SetEnvironmentVariable('ANOMALY_DETECTOR_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

echo export ANOMALY_DETECTOR_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE" >> /etc/environment && source /etc/environment

echo export ANOMALY_DETECTOR_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE" >> /etc/environment && source /etc/environment

サンプルデータをダウンロードする

このクイックスタートでは、request-data.csv ファイルを、GitHub のサンプルデータからダウンロードして使用します。

次を実行してサンプルデータをダウンロードすることもできます。

curl "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/anomalydetector/azure-ai-anomalydetector/samples/sample_data/request-data.csv" --output request-data.csv

異常を検出する

quickstart.py という名前の新しいPython ファイルを作成します。次に、任意のエディターまたは IDE で開きます。

quickstart.py の内容を次のコードに置き換えます。キー、エンドポイント、時系列データパスの環境変数名を追加するようにコードを変更します。

from azure.ai.anomalydetector import AnomalyDetectorClient
from azure.ai.anomalydetector.models import *
from azure.core.credentials import AzureKeyCredential
import pandas as pd
import os

API_KEY = os.environ['ANOMALY_DETECTOR_API_KEY']
ENDPOINT = os.environ['ANOMALY_DETECTOR_ENDPOINT']
DATA_PATH = "REPLACE_WITH_YOUR_LOCAL_SAMPLE_REQUEST_DATA_PATH" #example: c:\\test\\request-data.csv

client = AnomalyDetectorClient(ENDPOINT, AzureKeyCredential(API_KEY))

series = []
data_file = pd.read_csv(DATA_PATH, header=None, encoding='utf-8', date_parser=[0])
for index, row in data_file.iterrows():
    series.append(TimeSeriesPoint(timestamp=row[0], value=row[1]))

request = UnivariateDetectionOptions(series=series, granularity=TimeGranularity.DAILY)

change_point_response = client.detect_univariate_change_point(request)
anomaly_response = client.detect_univariate_entire_series(request)

for i in range(len(data_file.values)):
    if (change_point_response.is_change_point[i]):
        print("Change point detected at index: "+ str(i))
    elif (anomaly_response.is_anomaly[i]):
        print("Anomaly detected at index:      "+ str(i))

重要

運用環境では、Azure Key Vault。資格情報のセキュリティの詳細については、Azure AI サービス security に関する記事を参照してください。

python コマンドでクイックスタートファイルを指定してアプリケーションを実行します。
```
python quickstart.py
```

出力

Anomaly detected at index:      3
Anomaly detected at index:      18
Change point detected at index: 20
Anomaly detected at index:      21
Anomaly detected at index:      22
Anomaly detected at index:      23
Anomaly detected at index:      24
Anomaly detected at index:      25
Change point detected at index: 27
Anomaly detected at index:      28
Anomaly detected at index:      29
Anomaly detected at index:      30
Anomaly detected at index:      31
Anomaly detected at index:      32
Anomaly detected at index:      35
Anomaly detected at index:      44

結果を理解する

上記のコードでは、Azure AI Anomaly Detectorを 2 回呼び出します。 1 回目の呼び出しでは、detect_change_point メソッドを使ってサンプルデータ系列全体で傾向の変化点を調べます。この呼び出しからは、ChangePointDetectResponse という名前を付けた変数に格納されている change_point_request が返されます。次に、応答の is_change_point リストを反復処理して、ブール値 true であるすべての値のインデックスを出力します。

2 回目の呼び出しでは、detect_entire_series メソッドを使ってサンプルデータ系列全体で異常をチェックします。この呼び出しからは、EntireDetectResponse という名前を付けた変数に格納されている anomaly_response が返されます。応答の is_anomaly リストを反復処理して、ブール値 true であるすべての値のインデックスを出力します。または、リアルタイムデータでの異常検出にいっそう適した detect_last_point メソッドを使うこともできます。詳しくは、ベストプラクティスガイドに関する記事をご覧ください。

結果を視覚化する

サンプルデータ系列に関連する異常と変化点を表示するには、一般的なオープンソースライブラリ matplotlib を使います。

ライブラリをインストールする。
```
pip install matplotlib
```

quickstart.py ファイルを次のコードで変更します。

from azure.ai.anomalydetector import AnomalyDetectorClient
from azure.ai.anomalydetector.models import *
from azure.core.credentials import AzureKeyCredential
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib.dates as mdates
import os

API_KEY = os.environ['ANOMALY_DETECTOR_API_KEY']
ENDPOINT = os.environ['ANOMALY_DETECTOR_ENDPOINT']
DATA_PATH = "REPLACE_WITH_YOUR_LOCAL_SAMPLE_REQUEST_DATA_PATH" #example: c:\\test\\request-data.csv

client = AnomalyDetectorClient(ENDPOINT, AzureKeyCredential(API_KEY))

series = []
data_file = pd.read_csv(DATA_PATH, header=None, encoding='utf-8', date_parser=[0])
for index, row in data_file.iterrows():
    series.append(TimeSeriesPoint(timestamp=row[0], value=row[1]))

request = UnivariateDetectionOptions(series=series, granularity=TimeGranularity.DAILY)

change_point_response = client.detect_univariate_change_point(request)
anomaly_response = client.detect_univariate_entire_series(request)

for i in range(len(data_file.values)):
    temp_date_to_num = mdates.date2num(data_file.values[i])
    date= temp_date_to_num[0]
    if (change_point_response.is_change_point[i]):
        plt.plot(date,data_file.values[i][1], 's', color ='blue')
        print("Change point detected at index: "+ str(i))
    elif (anomaly_response.is_anomaly[i]):
        plt.plot(date,data_file.values[i][1], '^', color="red")
        print("Anomaly detected at index:      "+ str(i))
    else:
        plt.plot(date,data_file.values[i][1], 'o', color ='green')
plt.show()

重要

運用環境では、Azure Key Vault。資格情報のセキュリティの詳細については、Azure AI サービス security に関する記事を参照してください。

python コマンドでクイックスタートファイルを指定してアプリケーションを実行します。
```
python quickstart.py
```

出力

このコード例では、通常のデータポイントと変化点や異常を視覚化し、それらを簡単に区別できるように、matplotlib ライブラリを追加しました。変化点は青い四角形、異常は赤い三角形、通常のデータポイントは緑の円で表されます。グラフの y 軸の値を見やすくするため、matplotlib の date2num メソッドを使って日付を数値に変換します。

リソースをクリーンアップする

Anomaly Detector リソースをクリーンアップして削除したい場合は、リソースまたはリソースグループを削除できます。リソースグループを削除すると、それに関連付けられている他のリソースも削除されます。また、作成した環境変数を使用しない場合は、それらの削除を検討することもできます。

このクイックスタートでは、Anomaly Detector サービスと cURL を使用して、時系列データのバッチで異常を検出する方法について説明します。

Anomaly Detector に関する全体像については、概要記事をご覧ください。

前提条件

Azure サブスクリプション - 無料で作成します
Azure サブスクリプションを取得したら、Azure ポータルに Anomaly Detector リソースを作成して、キーとエンドポイントを取得します。デプロイされるまで待ち、 [リソースに移動] ボタンを選択します。 Free 価格レベル (F0) を使用してサービスを試用し、後から運用環境用の有料レベルにアップグレードすることができます。
異常をテストする時系列データの有効な JSON ファイル。独自のファイルがない場合は、Azure AI Foundry REST API リファレンスから sample.json ファイルを作成できます。

キーとエンドポイントを取得する

Anomaly Detector サービスに対する呼び出しを正しく行うには、次の値が必要です。

変数名	値
`ANOMALY_DETECTOR_ENDPOINT`	Azure ポータルでリソースを確認する際は、「Keys とエンドポイント」セクションにこの値があります。エンドポイントの例: `https://YOUR_RESOURCE_NAME.cognitiveservices.azure.com/`
`ANOMALY_DETECTOR_API_KEY`	API キーの値は、Azure ポータルでリソースを調べる時のキーとエンドポイントセクションにあります。 `KEY1` または `KEY2` を使用できます。

Azure ポータルでリソースに移動します。 [エンドポイントとキー] は [リソース管理] セクションにあります。エンドポイントとアクセスキーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1 または KEY2 を使用できます。常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。

環境変数を作成する

キーとエンドポイントの永続的な環境変数を作成して割り当てます。

重要

クラウドで実行されるアプリケーションに資格情報を格納しないように、 Azure リソースの管理された ID を使用して認証をMicrosoft Entra IDすることをお勧めします。

API キーは慎重に使用してください。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。 API キーを使用する場合は、Azure Key Vaultに安全に格納し、キーを定期的にローテーションし、ロールベースのアクセス制御とネットワークアクセス制限を使用してAzure Key Vaultへのアクセスを制限します。アプリで API キーを安全に使用する方法の詳細については、「Azure Key Vault を使用した API キー」を参照してください。

AI サービスのセキュリティの詳細については、「Authenticate requests to Azure AI サービス」を参照してください。

setx ANOMALY_DETECTOR_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

setx ANOMALY_DETECTOR_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

[System.Environment]::SetEnvironmentVariable('ANOMALY_DETECTOR_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')

[System.Environment]::SetEnvironmentVariable('ANOMALY_DETECTOR_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

echo export ANOMALY_DETECTOR_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE" >> /etc/environment && source /etc/environment

echo export ANOMALY_DETECTOR_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE" >> /etc/environment && source /etc/environment

異常を検出する

コマンドプロンプトで、次のコマンドを実行します。次の値をコマンドに挿入する必要があります。

Anomaly Detector サービスのサブスクリプションキー。
Anomaly Detector のエンドポイントアドレス。
異常をテストする時系列データの有効な JSON ファイル。独自のファイルがない場合は、Azure AI Foundry REST API リファレンスから sample.json ファイルを作成できます。

curl -v POST "%ANOMALY_DETECTOR_ENDPOINT%/anomalydetector/v1.0/timeseries/entire/detect"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: %ANOMALY_DETECTOR_API_KEY%"
-d "@path_to_sample_file.json"

完全なコマンドを 1 行で示した例:

curl -v POST "%ANOMALY_DETECTOR_ENDPOINT%/anomalydetector/v1.0/timeseries/entire/detect" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: %ANOMALY_DETECTOR_API_KEY%" -d "@c:\test\rest.json"

または、Bash シェルから cURL コマンドを実行している場合は、コマンドが少し異なります。

curl -v POST "$ANOMALY_DETECTOR_ENDPOINT/anomalydetector/v1.0/timeseries/entire/detect" -H "Content-Type: application/json" -H "Ocp-Apim-Subscription-Key: $ANOMALY_DETECTOR_API_KEY" -d "@c:\test\rest.json"

前提条件に示すサンプルデータを使用した場合は、次の結果を含む応答 200 が返されます。

{
  "expectedValues": [
    827.7940908243968,
    798.9133774671927,
    888.6058431807189,
    900.5606407986661,
    962.8389426378304,
    933.2591606306954,
    891.0784104799666,
    856.1781601363697,
    809.8987227908941,
    807.375129007505,
    764.3196682448518,
    803.933498594564,
    823.5900620883058,
    794.0905641334288,
    883.164245249282,
    894.8419000690953,
    956.8430591101258,
    927.6285055190114,
    885.812983784303,
    851.6424797402517,
    806.0927886943216,
    804.6826815312029,
    762.74070738882,
    804.0251702513732,
    825.3523662579559,
    798.0404188724976,
    889.3016505577698,
    902.4226124345937,
    965.867078532635,
    937.3200495736695,
    896.1720524711102,
    862.0087368413656,
    816.4662342097423,
    814.4297745524709,
    771.8614479159354,
    811.859271346729,
    831.8998279215521,
    802.947544797165,
    892.5684407435083,
    904.5488214533809,
    966.8527063844707,
    937.3168391003043,
    895.180003672544,
    860.3649596356635,
    814.1707285969043,
    811.9054862686213,
    769.1083769610742,
    809.2328084659704
  ],
  "upperMargins": [
    41.389704541219835,
    39.94566887335964,
    44.43029215903594,
    45.02803203993331,
    48.14194713189152,
    46.66295803153477,
    44.55392052399833,
    42.808908006818484,
    40.494936139544706,
    40.36875645037525,
    38.215983412242586,
    40.196674929728196,
    41.17950310441529,
    39.70452820667144,
    44.1582122624641,
    44.74209500345477,
    47.84215295550629,
    46.38142527595057,
    44.290649189215145,
    42.58212398701258,
    40.30463943471608,
    40.234134076560146,
    38.137035369441,
    40.201258512568664,
    41.267618312897795,
    39.90202094362488,
    44.46508252788849,
    45.121130621729684,
    48.29335392663175,
    46.86600247868348,
    44.80860262355551,
    43.100436842068284,
    40.82331171048711,
    40.721488727623544,
    38.593072395796774,
    40.59296356733645,
    41.5949913960776,
    40.14737723985825,
    44.62842203717541,
    45.227441072669045,
    48.34263531922354,
    46.86584195501521,
    44.759000183627194,
    43.01824798178317,
    40.70853642984521,
    40.59527431343106,
    38.45541884805371,
    40.46164042329852
  ],
  "lowerMargins": [
    41.389704541219835,
    39.94566887335964,
    44.43029215903594,
    45.02803203993331,
    48.14194713189152,
    46.66295803153477,
    44.55392052399833,
    42.808908006818484,
    40.494936139544706,
    40.36875645037525,
    38.215983412242586,
    40.196674929728196,
    41.17950310441529,
    39.70452820667144,
    44.1582122624641,
    44.74209500345477,
    47.84215295550629,
    46.38142527595057,
    44.290649189215145,
    42.58212398701258,
    40.30463943471608,
    40.234134076560146,
    38.137035369441,
    40.201258512568664,
    41.267618312897795,
    39.90202094362488,
    44.46508252788849,
    45.121130621729684,
    48.29335392663175,
    46.86600247868348,
    44.80860262355551,
    43.100436842068284,
    40.82331171048711,
    40.721488727623544,
    38.593072395796774,
    40.59296356733645,
    41.5949913960776,
    40.14737723985825,
    44.62842203717541,
    45.227441072669045,
    48.34263531922354,
    46.86584195501521,
    44.759000183627194,
    43.01824798178317,
    40.70853642984521,
    40.59527431343106,
    38.45541884805371,
    40.46164042329852
  ],
  "isAnomaly": [
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    true,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false
  ],
  "isPositiveAnomaly": [
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    true,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false
  ],
  "isNegativeAnomaly": [
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false,
    false
  ],
  "period": 12
}

詳細については、Azure AI Foundry REST API リファレンスを参照してください。

リソースをクリーンアップする

Azure AI サービスサブスクリプションをクリーンアップして削除する場合は、リソースまたはリソースグループを削除できます。リソースグループを削除すると、そのリソースグループに関連付けられている他のリソースも削除されます。

次のステップ

概念:

チュートリアル:

Power BI
Azure Databricks を使用したストリーミングデータの異常検出

次の方法で共有

クイックスタート: Univariate Anomaly Detector クライアント ライブラリを使用する

前提条件

セットアップ

新しい .NET Core アプリケーションを作成する

クライアント ライブラリをインストールする

キーとエンドポイントを取得する

環境変数を作成する

サンプル データをダウンロードする

異常を検出する

出力

コードの詳細

結果を理解する

リソースをクリーンアップする

前提条件

セットアップ

新しい Node.js アプリケーションを作成する

クライアント ライブラリをインストールする

キーとエンドポイントを取得する

環境変数を作成する

サンプル データをダウンロードする

異常を検出する

アプリケーションの実行

出力

結果を理解する

リソースをクリーンアップする

前提条件

セットアップ

キーとエンドポイントを取得する

環境変数を作成する

サンプル データをダウンロードする

異常を検出する

出力

結果を理解する

結果を視覚化する

出力

リソースをクリーンアップする

前提条件

キーとエンドポイントを取得する

環境変数を作成する

異常を検出する

リソースをクリーンアップする

次のステップ

その他のリソース

クイックスタート: Univariate Anomaly Detector クライアントライブラリを使用する

クライアントライブラリをインストールする

サンプルデータをダウンロードする

クライアントライブラリをインストールする

サンプルデータをダウンロードする

サンプルデータをダウンロードする