#背景
　本記事はAzure Log Analyticsの検索クエリをREST APIを使用してPowerShellで実行する方法について記載しています。REST APIから検索クエリを実行することで応用の幅が広がるのではないかと考え検証しました。結論として「Azure Log Analytics REST API」を使用することで実現できるのですが、私のようなREST APIの使用に習熟していない者にとってはその為の作業手順がそこそこ複雑でしたので記事として整理しました。

#方針
　冒頭に記載した通り「Azure Log Analytics REST API」を使用します。REST APIを呼び出す際にはPowerShellを使用して検索クエリを実行します。
　
#事前準備
　Azure サブスクリプションにてLog Analytics Workspaceを作成し、データソースとして仮想マシンを接続するなどして何らかのデータがLog Analytics Workspaceに保存されるようにしておきます。また、PowerShellスクリプトを実行する際にサブスクリプションIDとサブスクリプションが関連付けられているAzure AD のテナントIDが必要であるためこれらも事前に確認しておきます。

#手順概要
　続いて今回の作業手順の概要を以下に記載します。(1)～(4)を実行してREST APIを使用する準備を整え、最後にPowerShellスクリプトで検索クエリを実行します。

(1)Azure AD Web Applicationの作成
(2)Azure AD Web Applicationのアクセス許可設定
(3)Azure AD Web Applicationのクライアントシークレットの発行
(4)Log Analytics Workspaceのアクセス制御(IAM)設定

#手順詳細
(1)Azure AD Web Applicationの作成
①Azure ポータルへサインインします。

②「Azure Active Directory」を選択します。

③「アプリの登録」を選択します。

　
④「新規登録」を選択します。

⑤以下の通り設定し「登録」を選択します。
　・名前：任意(今回はAccess Log Analyticsとします。)
　・リダイレクトURL：http://localhost:3000/login

⑥Azure AD Web Applicationが作成されたことを確認します。

(2)Azure AD Web Applicationのアクセス許可設定
①(1)で登録した「Access Log Analytics」を選択します。

②「アプリケーションID」を控え、「APIのアクセス許可」を選択します。アプリケーションIDは後程PowerShellスクリプトを実行する際に使用します。

③「アクセス許可の追加」を選択します。

④「所属している組織で使用しているAPI」を選択します。

⑤「Log Analytics API」を選択します。

⑥「委任されたアクセス許可」を選択し、「Data.Read」にチェックを入れ「アクセス許可の追加」を選択します。

⑦「アクセス許可」が追加されたことを確認します。

(3)Azure AD Web Applicationのクライアントシークレットの発行
①(1)で登録した「Access Log Analytics」を選択します。

②「証明書とシークレット」を選択します。

③「新しいクライアントシークレット」を選択します。

④「追加」を選択します。

⑤「クライアントシークレット」の「値」を控えます。後ほどPowerShellスクリプトを実行する際に使用します。

(4)Log Analytics Workspaceのアクセス制御(IAM)設定
①Azure ポータルにて、事前に用意していた「Log Analytics Workspace」を選択します。

②「アクセス制御(IAM)」を選択します。

③「追加」-「ロールの割り当ての追加」を選択します。

④(1)で作成したアプリケーション(Access Log Analytics)に対して「Log Analytics 閲覧者」の役割を設定し「保存」を選択します。

⑤「Access Log Analytics」が「Log Analytics 閲覧者」として追加されたことを確認します。

#検索クエリを実行するPowerShellスクリプト
　以上で準備が整いました。続いて以下に検索クエリを実行するためのPowerShellスクリプトを記載します。
　※Azure サブスクリプションへのログインについては以下スクリプトでは割愛しています。

(1)パラメータ設定
本スクリプトを実行する上で必要なパラメータを以下に記載します。

①tenantId
Azure サブスクリプションが関連付けられているAzure AD テナントのテナントIDを確認し指定します。

$tenantId = "<Azure AD テナントID>"

②clientID
手順詳細(2)の②で確認したAzure AD Web ApplicationのアプリケーションIDを指定します。

$clientID = "<Azure AD アプリケーションID>"

③clientSecret
手順詳細(3)の④で確認したAzure AD Web Applicationのクライアントシークレットを指定します。

$clientSecret = "<クライアントシークレット>"

④subscriptionId
Azure サブスクリプションのサブスクリプションIDを確認し指定します。

$subscriptionId = "<サブスクリプションID>"

⑤workspaceRgName
Log Analytics Workspaceが存在するリソースグループの名称を指定します。

$workspaceRgName = "DefaultResourceGroup-EUS"

⑥workspacename
Log Analytics Workspaceの名称を指定します。

$workspacename = "DefaultWorkspace-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-EUS"

(2)認証Tokenの取得
以下のスクリプトにてREST APIを実行するための認証Tokenを取得します。

$loginURL       = "https://login.microsoftonline.com/$tenantId/oauth2/token"
$resource       = "https://management.azure.com/"         
$body           = @{grant_type="client_credentials";resource=$resource;client_id=$clientId;client_secret=$clientSecret}
$oauth          = Invoke-RestMethod -Method Post -Uri $loginURL -Body $body
$headerParams = @{"Authorization" = "Bearer " + $oauth.access_token}

(3)検索クエリ
Log Analyticsで実行する検索クエリを記載します。
以下の「body」のシングルクォーテーション内に任意の検索クエリを記載します。
以下では例として2019年12月1日から12月31日までのすべてのHeartbeat通信を検索するクエリを記載しています。

$body = @{query = 
'let startdatetime=datetime(2019-12-01T00:00:00);
let enddatetime=datetime(2019-12-30T23:59:59);
Heartbeat | where TimeGenerated between(startdatetime .. enddatetime)
'
}| ConvertTo-Json

(4)REST APIの呼び出し(検索クエリの実行)
REST APIを呼び出し、検索クエリの実行結果を変数に格納します。

$url="https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$workspaceRgName/providers/Microsoft.OperationalInsights/workspaces/$workspacename/api/query?api-version=2017-01-01-preview"
$result = Invoke-RestMethod -UseBasicParsing -Headers $headerParams -Uri $url -Method Post -Body $body -ContentType "application/json"

(5)検索クエリ結果の整形
そのままの形式では閲覧に適さない為CSV形式に整形します。以下の整形の為のスクリプトについてはこちらを参考にしました。ここで1点注意点があります。REST APIの実行結果を格納した変数 $resultを確認するとテーブルが4つ(Table_0/Table_1/Table_2/Table_3)存在します。このうちクエリ結果が格納されているのはTable_0のみであるため、整形の際にはTable_0のデータのみを抽出します。

$headerRow = $null
$headerRow = $result.tables[0].columns | Select-Object ColumnName
$columnsCount = $headerRow.Count
$logData = @()
foreach ($row in $result.tables[0].rows) {
    $data = new-object PSObject
    for ($i = 0; $i -lt $columnsCount; $i++) {
        $data | add-member -membertype NoteProperty -name $headerRow[$i].ColumnName -value $row[$i]
    }
    $logData += $data
    $data = $null
}

(6)CSV出力
整形完了後以下のようにして任意のパスにcsvファイルとして出力します。例としてローカルPCのデスクトップを指定しています。

$logData | export-csv C:\Users\XXXXXX\Desktop\logAnalytics.csv -NoTypeInformation

※改めてスクリプト全体を以下に記載します。

#パラメータ設定
$tenantId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$clientId       = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"      
$clientSecret   = "********************************"  

$subscriptionId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$workspaceRgName="DefaultResourceGroup-EUS"
$workspacename = "DefaultWorkspace-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-EUS"

#Tokenの取得
$loginURL       = "https://login.microsoftonline.com/$tenantId/oauth2/token"
$resource       = "https://management.azure.com/"         
$body           = @{grant_type="client_credentials";resource=$resource;client_id=$clientId;client_secret=$clientSecret}
$oauth          = Invoke-RestMethod -Method Post -Uri $loginURL -Body $body
$headerParams = @{"Authorization" = "Bearer " + $oauth.access_token} 

#検索クエリ
$body = @{query = 
'let startdatetime=datetime(2019-12-01T00:00:00);
let enddatetime=datetime(2019-12-30T23:59:59);
Heartbeat | where TimeGenerated between(startdatetime .. enddatetime)
'
}| ConvertTo-Json

#APIの呼び出し(検索クエリの実行)
$url="https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$workspaceRgName/providers/Microsoft.OperationalInsights/workspaces/$workspacename/api/query?api-version=2017-01-01-preview"
$result = Invoke-RestMethod -UseBasicParsing -Headers $headerParams -Uri $url -Method Post -Body $body -ContentType "application/json"

#検索クエリ結果の整形
$headerRow = $null
$headerRow = $result.tables[0].columns | Select-Object ColumnName
$columnsCount = $headerRow.Count
$logData = @()
foreach ($row in $result.tables[0].rows) {
    $data = new-object PSObject
    for ($i = 0; $i -lt $columnsCount; $i++) {
        $data | add-member -membertype NoteProperty -name $headerRow[$i].ColumnName -value $row[$i]
    }
    $logData += $data
    $data = $null
}

#CSV出力
$logData | export-csv C:\Users\XXXXXX\Desktop\logAnalytics.csv -NoTypeInformation

#実行結果
　上述のスクリプトを実行することで以下のようなcsvファイルが出力されます。勿論Azure ポータルで検索クエリの実行結果をエクスポートすることも可能ですので、これだけではわざわざREST APIを使用する意味は薄いと言えます。応用方法については今後の課題として引き続き検討したいと思います。

#参考情報
・Azure REST API を使ってみよう
・Azure Log Analytics REST API
・Using PowerShell to query Azure Log Analytics via the REST API
・Azure AD Log Analytics KQL queries via API with PowerShell