Azure Monitor REST API walkthroughの更新でまず押さえるべき点は、「Azure Monitorの監視機能そのものが大きく変わった」というより、REST APIを使ってメトリック定義、メトリック値、ディメンション、アクティビティログを取得する実装手順が、より実務向けに整理されたということです。特に管理者や開発者は、認証時のスコープ指定、/providers/microsoft.insights/を含むAPIパス、APIバージョン、複数リソースメトリック取得時の権限、アクティビティログ取得時の時間範囲とタイムアウトを確認する必要があります。
今回のポイントは、既存のAzure Monitor運用をすぐ止めるような破壊的変更ではありません。ただし、社内ダッシュボード、監視データのETL、独自アラート基盤、監査ログ収集などでAzure Monitor REST APIを直接呼び出している場合、古いサンプルのまま実装していると、認証エラー、空の時系列データ、想定外の集計、スロットリングでつまずく可能性があります。
Azure Monitor REST API walkthroughの更新で確認すべき結論
公式の「Azure monitoring REST API walkthrough」は、Azure Monitor REST APIを使って、メトリック定義、ディメンション値、メトリック値、アクティビティログなどを取得する流れを説明するドキュメントです。Azure Monitorの多くのREST APIはAzure Resource Manager、つまりARMのコントロールプレーンAPIとして扱われます。公式ページでも、Azure Monitor APIでメトリック定義やメトリック値を取得し、アプリケーションや分析用データベースで利用できることが説明されています。(Microsoft Learn)
2026年5月上旬の公式GitHub履歴では、このウォークスルー周辺に複数の更新が記録されています。具体的には、2026年4月29日にトークン取得の説明がresource指定からscope指定へ修正され、2026年5月4日にActivity Log、REST walkthrough、query limits関連の更新、2026年5月5日にActivity Log APIのタイムアウト設定と例の更新が反映されています。(GitHub)
実務上は、次のように理解すると判断しやすくなります。
| 確認項目 | 今回の要点 | 影響を受けやすい人 |
|---|---|---|
| 認証 | Microsoft Entra IDでトークンを取得し、ARM向けのスコープを使う | REST APIをアプリやバッチから呼ぶ開発者 |
| APIパス | 対象リソースIDの後ろに/providers/microsoft.insights/を付ける | 404や400で詰まる実装担当者 |
| メトリック取得 | 定義、ディメンション、値の順に確認する | 監視ダッシュボードや集計基盤の担当者 |
| 複数リソース取得 | サブスクリプションスコープ、リージョン、リソース種類、権限を確認する | SRE、クラウド管理者 |
| アクティビティログ | 90日範囲、$filter、Preferヘッダー、タイムアウトを確認する | 監査、セキュリティ、運用管理者 |
何が変わったのか：サービス仕様変更ではなく、実装ガイドの明確化
今回の更新は、Azure Monitorのメトリックやアクティビティログの意味が変わる変更ではなく、REST APIを使う際に間違えやすい部分が整理されたものです。
特に重要なのは、次の3点です。
認証トークンはARM向けスコープを意識する
Azure Monitor APIへのリクエストは、Azure Resource Managerの認証モデルに従い、Microsoft Entra IDで認証します。公式ウォークスルーでは、サービスプリンシパルを作成し、アクセストークンを取得する方法が示されています。現在の説明では、トークン要求のスコープとしてhttps://management.azure.com/.defaultを使うことが明記されています。 (Microsoft Learn)
実務でよくある失敗は、古いサンプルにあるresource=https://management.azure.com形式だけを前提に実装してしまうことです。既存のスクリプトをすぐ全面改修する必要があるとは限りませんが、新規実装やSDKベースの実装では、scopeを前提に設計した方が今後のメンテナンスはしやすくなります。
最小構成の確認用であれば、Azure CLIでアクセストークンを取得し、Authorizationヘッダーに入れて呼び出す形が分かりやすいです。
TOKEN=$(az account get-access-token --query accessToken -o tsv)
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
"https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Compute/virtualMachines/<vm-name>/providers/microsoft.insights/metricDefinitions?api-version=2018-01-01"本番環境では、クライアントシークレットを長期保存する実装よりも、可能な限りマネージドIDや証明書ベースの認証を検討すべきです。また、Azure SDKの認証ベストプラクティスでは、DefaultAzureCredentialは便利な一方で、本番環境ではどの資格情報が使われるかを明確にするため、ManagedIdentityCredentialなどの確定的な資格情報を使う考え方が示されています。(Microsoft Learn)
APIの入口はmanagement.azure.comが基本
Azure MonitorのARM系APIは、標準のARMエンドポイントであるhttps://management.azure.com/配下で呼び出します。REST API Indexでは、Azure Monitor API、Application Insights API、Azure Monitor Logs APIが分けて整理されており、Azure Monitorのメトリック定義・メトリック値・メトリックバッチなどはResource metricsの操作グループとして示されています。(Microsoft Learn)
一方で、Azure Monitor Logsの取り扱いは少し違います。Logs ingestionはDCEまたはDCRログ取り込みエンドポイントを使い、Logs queryはapi.loganalytics.ioまたはapi.loganalytics.azure.comを使います。つまり、メトリック取得、アクティビティログ取得、Log Analyticsクエリ、ログ取り込みを同じREST APIとして雑に扱わないことが重要です。(Microsoft Learn)
リソースIDの後ろに/providers/microsoft.insights/を付ける
メトリック定義やメトリック値を取得する場合、対象AzureリソースのIDに対して、さらに/providers/microsoft.insights/metricDefinitionsまたは/providers/microsoft.insights/metricsを付けます。公式ウォークスルーでも、この/providers/microsoft.insights/を含めることが重要点として示されています。(Microsoft Learn)
たとえば仮想マシンのメトリック定義を取得する場合、考え方は次のようになります。
<Resource ID>/providers/microsoft.insights/metricDefinitions?api-version=2018-01-01失敗しやすいのは、VMやStorage AccountなどのリソースIDだけでAPIを呼び、Azure Monitor側のプロバイダー部分を付け忘れるケースです。この場合、権限が正しくても期待したメトリック定義は取得できません。
対象者：誰が確認すべきか
今回のAzure Monitor REST API walkthrough更新で特に確認すべきなのは、Azureポータルだけで監視している人ではなく、API経由で監視データを取り出している人です。
クラウド管理者・SRE
複数サブスクリプションや複数リソースを横断してメトリックを集計している場合、APIのスコープと権限を見直す必要があります。複数リソースのメトリック取得では、APIがサブスクリプションレベルで動作し、1回のクエリで指定できるリソース種類とリージョンに制限があります。さらに、複数リソースメトリックAPIを使うには、対象サブスクリプション自体にMonitoring Reader権限が必要です。(Microsoft Learn)
アプリケーション開発者
社内ポータル、運用ダッシュボード、BI連携、監視データの定期収集バッチなどでREST APIを直接呼んでいる場合、認証トークン、APIバージョン、メトリック名、ディメンション名を確認してください。
特に、レスポンスに含まれるlocalizedValueではなく、APIクエリではname.valueを使う設計にするのが安全です。表示名は人間向けですが、実装で使う識別子は変換やローカライズの影響を受けにくい値を使うべきです。
セキュリティ・監査担当者
アクティビティログをAPIで取得している場合、90日以内の時間範囲、$filter、サブスクリプション・テナント・管理グループ単位の違いを確認してください。Azure MonitorのActivity logは管理操作を記録し、既定で収集されますが、保持期間は90日です。長期保管や高度な分析が必要な場合は、診断設定でLog Analyticsワークスペースなどに送る設計が必要です。(Microsoft Learn)
メトリック取得は「定義→ディメンション→値」の順で設計する
Azure Monitor REST APIでメトリックを扱うときは、いきなり値を取りに行くより、次の順番で設計すると失敗が減ります。
| 手順 | 確認する内容 | なぜ重要か |
|---|---|---|
| メトリック定義を取得 | 利用可能なメトリック名、単位、集計方法、保持期間 | サービスごとに使えるメトリックが異なるため |
| ディメンション値を取得 | ApiName、GeoType、ResponseTypeなどの値 | フィルター条件の誤りを防ぐため |
| メトリック値を取得 | timespan、interval、aggregation、$filter | 必要な粒度と集計でデータを取得するため |
公式ウォークスルーでは、Metric Definitions APIで利用可能なメトリック定義を取得し、その後、Metrics APIでディメンション値やメトリック値を取得する流れが説明されています。メトリック定義APIでは、ディメンションを扱うために2018-01-01以降のAPIバージョンが推奨され、ディメンション値や多次元メトリック値の取得では2019-07-01以降が必要とされています。(Microsoft Learn)
実装例：メトリック定義を取得する
RESOURCE_ID="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>"
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
"https://management.azure.com${RESOURCE_ID}/providers/microsoft.insights/metricDefinitions?api-version=2018-01-01"このレスポンスで見るべき項目は、主に次の通りです。
| 項目 | 見る理由 |
|---|---|
name.value | APIで指定するメトリック名 |
unit | Bytes、Count、Percentなどの単位 |
primaryAggregationType | 代表的な集計方法 |
supportedAggregationTypes | 使える集計方法 |
metricAvailabilities | 取得できる粒度と保持期間 |
dimensions | フィルターや系列分割に使える軸 |
ここを確認せずに、AverageやTotalを決め打ちすると、サービスによっては意味のない集計になります。たとえば、容量系メトリックでは平均値が自然でも、リクエスト数やトランザクション数では合計値を見るべきケースが多くなります。
ディメンションの扱いで失敗しやすいポイント
Azure Monitorの多次元メトリックでは、ディメンションを使うことで「API名別」「レスポンスタイプ別」「リージョン種別」などに分けて値を取得できます。ただし、ディメンションは便利な一方で、クエリの書き方を間違えると空の結果や過剰な時系列を返す原因になります。
公式ウォークスルーでは、ディメンション値を取得する場合にresultType=metadataを使うこと、ワイルドカードフィルターは1つのディメンションに限られることが説明されています。(Microsoft Learn)
たとえば、TransactionsメトリックでApiNameごとの値を確認したい場合、まずディメンション値を取得してから、必要なAPI名だけに絞ると安全です。
悪い例は、存在するか分からない値をいきなりフィルターに入れることです。
$filter=ApiName eq 'UnknownOperation'このような指定では、データがないのか、フィルターが間違っているのか判断しにくくなります。
良い進め方は、次の順番です。
- メトリック定義で
dimensionsを確認する resultType=metadataでディメンション値を取得する- 実在する値だけを
$filterに指定する topとorderbyで返す系列数を制御する
多次元メトリックを大量に取得すると、時系列の数が増えてレスポンスが重くなります。ダッシュボード用途では、すべての系列を取得するより、上位N件を取得する設計の方が安定します。
複数リソースのメトリック取得で確認すべき制限
複数リソースのメトリックをまとめて取得できるAPIは便利ですが、単一リソースのメトリックAPIと同じ感覚で使うと失敗します。公式ウォークスルーでは、複数リソースメトリックAPIについて、サブスクリプションレベルで動作すること、1回のクエリで指定できるリソース種類は1つであること、1つのAzureリージョンを指定する必要があることが説明されています。(Microsoft Learn)
特に重要なのは権限です。単一リソースのメトリック取得では対象リソースに対するMonitoring Reader権限で足りる場合がありますが、複数リソースメトリックAPIはサブスクリプションレベルAPIです。そのため、個々のリソースすべてにMonitoring Readerが付いていても、サブスクリプション自体にMonitoring Readerがないと失敗します。(Microsoft Learn)
複数VMのCPU使用率をまとめて見る場合の考え方は次の通りです。
/subscriptions/<subscription-id>/providers/microsoft.insights/metrics
?metricnames=Percentage CPU
®ion=eastus
&metricNamespace=microsoft.compute/virtualmachines
&$filter=Microsoft.ResourceId eq '*'
&api-version=2021-05-01Microsoft.ResourceId eq '*'を付けると、対象サブスクリプションとリージョン内の各リソースごとに別々の時系列として返す意図を明確にできます。付けない場合、条件によってはリソース横断で集計された1本の時系列として扱われ、期待と違うグラフになる可能性があります。(Microsoft Learn)
アクティビティログ取得で確認すべきポイント
アクティビティログは、Azureリソースに対する作成、更新、削除、デプロイ失敗などの管理操作を確認するための重要なログです。Azure Monitorではアクティビティログが既定で収集されますが、通常は読み取り操作をすべて記録するものではありません。また、既定保持は90日です。(Microsoft Learn)
REST APIで取得する場合は、$filterに少なくともeventTimestampの開始値を含める必要があります。公式ドキュメントでは、サブスクリプション、リソースグループ、特定リソース、リソースプロバイダー、相関IDなどで絞り込むフィルター例が整理されています。(Microsoft Learn)
実装で注意すべき時間範囲
アクティビティログAPIでは、広すぎる範囲を一度に取得しようとすると、レスポンスが重くなります。月次監査のために大量取得する場合でも、1か月分を一気に取得するのではなく、日単位や数日単位に分割する設計が安全です。
$filter=eventTimestamp ge '2026-03-01T00:00:00Z' and eventTimestamp le '2026-03-02T00:00:00Z'また、Activity Log REST APIの最大タイムアウトは75秒で、クライアント側の待機時間を明示するためにPreferヘッダーを使う例が示されています。2026年5月上旬の更新履歴でも、Activity Log APIのタイムアウト設定と例の更新が記録されています。(Microsoft Learn)
Prefer: wait=75長期保管や高度なクエリが必要な場合は、アクティビティログをLog Analyticsワークスペースへエクスポートし、AzureActivityテーブルで分析する構成を検討します。公式ドキュメントでも、長期保持、他ログとの相関、複雑なログアラートなどの用途ではLog Analyticsへの送信が示されています。(Microsoft Learn)
管理者が確認すべき設定チェックリスト
Azure Monitor REST APIを運用で使う前に、管理者は次の項目を確認してください。
| チェック項目 | 確認内容 | 見落とした場合の影響 |
|---|---|---|
| IDの種類 | ユーザー、サービスプリンシパル、マネージドIDのどれで呼ぶか | 退職者アカウントや個人権限に依存する |
| RBACスコープ | リソース、リソースグループ、サブスクリプションのどこに権限を付けるか | 401または403で失敗する |
| Monitoring Reader | メトリックやログ参照に必要な読み取り権限があるか | APIは成功せず、監視データを取得できない |
| APIバージョン | ディメンションや多次元メトリックに対応したバージョンか | ディメンションが取得できない |
| リージョン指定 | 複数リソースメトリックで正しいリージョンを指定しているか | 空の時系列になる |
| 取得間隔 | intervalとtimespanが用途に合っているか | データ量過多または粒度不足になる |
| リトライ | 429、529、タイムアウト時の再試行を実装しているか | 一時的な負荷でバッチ全体が失敗する |
| 長期保持 | Activity logを90日超で保持する必要があるか | 監査時にログが残らない |
Monitoring Readerロールは、メトリックやログなどの監視データを読み取れる組み込みロールです。公式のAzure RBACドキュメントでも、Monitoring Readerは監視データを読み取れるロールとして説明されています。(Microsoft Learn)
開発者が確認すべき実装チェックリスト
開発者は、APIを呼ぶコードの中で次の点を確認してください。
認証を毎回取り直していないか
高頻度にAPIを呼ぶアプリで、毎回新しい資格情報インスタンスを作ったり、毎回トークン取得を強制したりすると、Microsoft Entra ID側の負荷やスロットリングにつながります。Azure Identityのベストプラクティスでも、資格情報インスタンスを再利用し、アクセストークン要求数を減らすことが推奨されています。(Microsoft Learn)
メトリック名を表示名で指定していないか
レスポンスにはlocalizedValueが含まれることがありますが、APIクエリで使うのは基本的にname.valueです。日本語表示やポータル表示名を見て、そのままAPIパラメータに入れると失敗することがあります。
URLエンコードを忘れていないか
Percentage CPUのように空白を含むメトリック名、$filter、ISO 8601形式のtimespanなどは、実装言語やHTTPクライアントによってURLエンコードの扱いが変わります。手動で文字列結合するより、HTTPクライアントのクエリパラメータ機能を使う方が安全です。
空の時系列をエラー扱いしていないか
公式ウォークスルーでは、指定した時間範囲やフィルターに該当データがない場合、空のtimeseriesが返ることがあると説明されています。空の結果は必ずしもAPI障害ではありません。未来の日付を指定した、リージョンを間違えた、ディメンション値が存在しない、対象リソースに該当メトリックがない、といった原因を切り分ける必要があります。(Microsoft Learn)
よくあるトラブルと対処法
| 症状 | 主な原因 | 対処 |
|---|---|---|
| 401または403になる | RBAC不足、サブスクリプションスコープ権限不足 | Monitoring Readerの割り当て範囲を確認する |
| 404になる | リソースID誤り、/providers/microsoft.insights/漏れ | Azure portalのJSONビューやCLIでリソースIDを確認する |
| メトリック定義は取れるが値が空 | 時間範囲、リージョン、フィルターが不一致 | timespanとディメンション値を確認する |
| ディメンションが使えない | 古いAPIバージョンを指定している | 2019-07-01以降を検討する |
| 複数VMの値が1本に集計される | Microsoft.ResourceId eq '*'を指定していない | リソースごとの時系列を返すフィルターを入れる |
| Activity logが途中で失敗する | 範囲が広い、タイムアウト、取得量が多い | 時間範囲を分割し、Prefer: wait=75を使う |
| 529が返る | メトリックバックエンド側のスロットリング | 指数バックオフで再試行する |
公式ウォークスルーでも、メトリック取得時の529はバックエンド側のスロットリングを示し、指数バックオフによる再試行が推奨されています。(Microsoft Learn)
既存環境での移行・見直し手順
既存の監視連携を壊さずに見直すなら、次の順番で進めると安全です。
現在のAPI呼び出しを棚卸しする
まず、どの処理がAzure Monitor REST APIを呼んでいるかを洗い出します。対象は、監視ダッシュボード、夜間バッチ、データレイクへのエクスポート、障害解析ツール、独自アラート基盤などです。
この時点で、次の情報を一覧化します。
| 項目 | 例 |
|---|---|
| 呼び出し元 | Azure Functions、VM、GitHub Actions、社内サーバー |
| 認証方式 | ユーザー、サービスプリンシパル、マネージドID |
| API種別 | metricDefinitions、metrics、activity log、Log Analytics query |
| APIバージョン | 2018-01-01、2019-07-01、2021-05-01など |
| 取得頻度 | 1分ごと、5分ごと、日次 |
| 権限スコープ | リソース、リソースグループ、サブスクリプション |
認証方式を本番向けに整理する
個人ユーザーのAzure CLIログインに依存している処理は、本番運用には向きません。Azure上で動く処理ならマネージドID、外部CI/CDやオンプレミス処理ならサービスプリンシパルやフェデレーション認証を検討します。
クライアントシークレットを使う場合は、次の点を必ず確認してください。
- シークレットをソースコードやCIログに出していない
- 有効期限切れを監視している
- ローテーション手順がある
- 最小権限のRBACになっている
単一リソースAPIと複数リソースAPIを分ける
単一リソースの詳細監視と、サブスクリプション全体の横断集計は設計を分けるべきです。単一リソースAPIは障害調査や個別ダッシュボードに向いています。複数リソースAPIは、同じリソース種類・同じリージョンのリソースを一覧的に比較する用途に向いています。
無理に1つのAPI呼び出しにまとめるより、用途ごとに最適なAPIを使い分ける方が、権限設計もトラブルシューティングも簡単になります。
Activity logは90日を超える要件を先に決める
監査やインシデント調査で90日を超えるログが必要なら、REST APIで都度過去ログを取りに行く設計では不十分です。Activity logは既定では90日保持のため、長期保持が必要な組織では、Log Analytics、Storage、Event Hubsなどへのエクスポート設計を先に決めておく必要があります。(Microsoft Learn)
すぐに取るべきアクション
Azure Monitor REST APIを使っている環境では、まず次の5つを確認してください。
- トークン取得でARM向けスコープを意識した実装になっているか
- APIパスに
/providers/microsoft.insights/が正しく入っているか - メトリック定義、ディメンション、値の順に取得できるか
- 複数リソース取得でサブスクリプション権限、リージョン、リソース種類を確認しているか
- Activity logの90日保持、
$filter、Preferヘッダー、取得範囲分割を設計しているか
今回のAzure Monitor REST API walkthrough更新は、既存のAzure Monitor運用を大きく変えるものではありません。しかし、REST API連携を長く安定運用するには、認証、権限、APIバージョン、ディメンション、タイムアウト、スロットリングをあらためて確認する良いタイミングです。特に、古いサンプルコードをコピーしたまま運用している場合は、まず検証環境で現在の公式ウォークスルーに沿ってAPI呼び出しを再確認し、その後、本番の監視基盤へ段階的に反映していきましょう。
コメント