SE の雑記

Log Analytics API について少し整理しておきたい内容がありましたので、調べた内容をメモとして残しておきたいと思います。

Log Analytics で使用可能な API

Log Analytics で使用可能な API ですが、大きく分けて次の二種類があり、用途に応じてこれらの API を使い分けることになります。

• Log Analytics REST API
• HTTP データコレクター API (プレビュー)

Log Analytics REST API

Log Analytics REST API は、Log Analytics ワークスペースを操作するための API となり、Azure Monitor Log Analytics API / Log Analytics Query API としてドキュメント化されているものになります。

Log Analytics ワークスペースのリソースの操作や、ログに対してクエリを実行する場合には、この REST API を使用することになります。

API の使用方法については、Azure Monitor Log Analytics API の概要 から確認することができ、各 REST API の詳細については、Log Analytics REST API リファレンス で確認することができます。

主に使用するものとしては、Query の API を使用した、蓄積されているログに対してのクエリ実行となるのではないでしょうか。

変わったものとしては、Purge があり、Log Analytics のテーブルから特定の情報を削除することもできたりします。

以下のドキュメントも参考となります。

• Query – Execute
• Azure Monitor Log Analytics API にアクセスする

Log Analytics REST API の認証方法

Log Analytics REST API を使用した場合、認証方式としては、「Azure Active Directory OAuth2 Flow」を使用することになり、Microsoft ID プラットフォームと暗黙的な許可のフロー を使用して、トークンを取得し、そのトークンを用いて API を呼び出すことになります。

スクリプトなどから呼び出す場合は、Azure AD にアプリケーションの登録を行い、クライアント ID / クライアントシークレットを使用して、API の呼び出しを行います。

アクセス制御については、API により操作をしたい Log Analytics の IAM により制御ができますので上述のクエリの API を実行するのであれば、AAD に登録したアプリケーションでに対して「Log Analytics 閲覧者」のロールを付与することで、API のコールができるようになります。

Data Factory や、Synapse の Managed Identity を Log Analytics 閲覧者に設定すれば、パイプラインから REST API を呼び出す際に認証方式として マネージド ID をしてすることで容易に API を呼び出すことができます。

私の場合は、Front Door のアクセスログを操作する際に API を使用しており、PowerShell や Data Factory のパイプラインで操作をしています。サンプルとしては次のような内容になるかと。

PowerShell

PowerShell から トークンを取得して、クエリを実行する際には次のような流れとなります。

$tenantId = "xxxxxxxxxxxxxxxxx"
$workspaceId = "xxxxxxxxxxxxxxx"

$clientId = "xxxxxxxxxxxxxxxxxxxxxxxx"
$clientSecret = "xxxxxxxxxxxxxxxxxxxx"

# https://docs.microsoft.com/ja-jp/azure/active-directory/develop/v2-oauth2-implicit-grant-flow

$uri = "https://login.microsoftonline.com/{0}/oauth2/token" -f $tenantId
$body = @{
    "grant_type"="client_credentials"
    "resource"="https://api.loganalytics.io"
    "client_id"= $clientId
    "client_secret" = $clientSecret
}
$results = Invoke-RestMethod -Method "POST" -Body $body -Uri $uri


# API
# https://docs.microsoft.com/ja-jp/rest/api/loganalytics/
# https://docs.microsoft.com/ja-jp/azure/azure-monitor/logs/api/overview
# https://docs.microsoft.com/ja-jp/azure/azure-monitor/logs/data-collector-api
# https://docs.microsoft.com/ja-jp/rest/api/loganalytics/dataaccess/query/execute

# API Limite
# https://docs.microsoft.com/ja-jp/azure/azure-monitor/service-limits#log-analytics-workspaces

$headers = @{
    "Content-Type" = "application/json"
    "Authorization"=("Bearer {0}" -f $results.access_token)
}
$body = @{
        "query" = `
        "AzureDiagnostics | where Category =~ 'FrontDoorAccessLog' and TimeGenerated  >= datetime('2022-01-01T00:00') and TimeGenerated < datetime('2022-06-29T01:00') | sort by TimeGenerated asc"
}
$uri = "https://api.loganalytics.io/v1/workspaces/{0}/query" -f $workspaceId

$results= Invoke-WebRequest -Method "Post" -Uri $uri -Headers $headers -Body ($body | ConvertTo-Json)
$results.tables[0].rows.count
[/sourcecode]

Data Factory / Synapse パイプライン

Data Factory や Synapse Analytics のパイプラインで、REST のデータソースから、クエリを実行するということも可能です。

API 経由で実行したクエリの結果を、次のようなマッピングを指定することで、他のデータソースで永続化することもでき、私の場合は Tumbling windows のトリガーで Log Analytics Workspace に格納されている Front Door のアクセスログを、SQL Database にコピーするというようなことを行っています。

HTTP データコレクター API  (プレビュー)

HTTP データコレクター API は、Log Analytics ワークスペースの操作ではなく、「Log Analytics ワークスペースに任意のログデータを送信する」際に使用することができる API となります。

この API を使用することで、任意のデータを Log Analytics にカスタムデータとして書き込むことができます。

以前作成した、EZMonitor もメトリクスの格納先には、Log Analytics を使用しており、データの送信には、この HTTP データコレクター API を使用しています。

HTTP データコレクター API の認証方式

Log Analytics REST API では、AAD のアプリや IAM を使用した認証を行っていましたが、HTTP データコレクター API については、Log Analytics ワークスペースのワークスペース ID と、ワークスペース ID のキーを使用した認証を行うため、認証の方式が Log Analytics REST API と異なります。

使用方法については、PowerShell のサンプル として、サンプルの全文が公開されていますので、実際に使用する際にはこの内容を確認すれば問題ないかと思います。

各 API の制限

Log Analytics REST API / HTTP データコレクター API ともに、API の制限があり、制限については、Log Analytics ワークスペース に記載されており、影響するのが以下の記載となります。

Log Analytics REST API であれば、クエリを実行した際に取得できる最大のレコード数は「500,000」(50 万) となり、この件数を超える場合にはレスポンスにエラーの情報が含まれるようになり、クエリの実行結果をすべて取得することができないことを表します。

データコレクター API については 1 回の呼び出しで送信できるデータの最大は 30 MB となるため、それ以上のデータを送信する場合には分割が必要となります。

少量データを取り扱っている場合は、これらの制約は影響しないと思いますが、大量のデータを処理する場合にはこれらの制約も意識しておく必要があるかと。