MENU

Azure REST API v2026-05-01-previewの変更点：CloudHealth動的しきい値対応を解説

Azure

Azure REST APIの「v2026-05-01-preview API version with dynamic threshold support」は、AzureのMicrosoft.CloudHealthリソースプロバイダーで、シグナル定義の評価ルールに動的しきい値を追加する更新です。結論からいうと、CloudHealthのヘルス判定やアラートをREST API、IaC、独自ツール、生成SDKで管理しているチームは、api-versionの切り替え可否、SignalOperatorの新値Dynamic、thresholdの必須チェック、SDKのenum処理を確認する必要があります。なお、対象PRは本稿執筆時点でDraftとして表示されているため、正式反映前に仕様が変わる可能性があります。(GitHub)

目次

Azure REST API v2026-05-01-previewで何が変わるのか

今回の更新は、Azure REST API全体の一律変更ではなく、Microsoft.CloudHealthのCloudHealth API仕様に新しいプレビューAPIバージョン2026-05-01-previewを追加する内容です。PRでは、CloudHealth API specを拡張し、シグナル定義に対して動的しきい値評価を導入すると説明されています。具体的には、SignalOperatorへのDynamic追加、動的しきい値利用時のthreshold任意化、DynamicThresholdSensitivity、lookBackWindow、新バージョン用のexamplesとswaggerが含まれます。(GitHub)

既存の2026-01-01-preview向けMicrosoft Learnリファレンスでは、ThresholdRuleV2のthresholdは必須で、operatorの値もEqual、GreaterThan、GreaterThanOrEqual、LessThan、LessThanOrEqual、NotEqualなどの静的比較が中心でした。つまり今回のポイントは、「固定値と比較する監視ルール」から、「過去のシグナル値を使って変動を評価するルール」へ拡張される点です。(Microsoft Learn)

確認項目これまでの考え方v2026-05-01-previewでの変更点実務で見るべきポイント
APIバージョン2026-01-01-previewなど既存バージョンを指定2026-05-01-previewが追加既存テンプレートやREST呼び出しのapi-versionを不用意に一括変更しない
評価ルール固定しきい値をthresholdで指定operator: "Dynamic"が利用可能enumを固定値だけで処理しているコードを修正する
thresholdしきい値として必須動的しきい値では不要、静的operatorでは必要バリデーションを「常に必須」から「operator別」に変更する
感度固定しきい値では不要Low、Medium、Highを指定可能ノイズが多い監視では最初からHighにしない
履歴期間固定値なので不要lookBackWindowで過去データの参照期間を指定日次・週次の変動パターンを考えて設定する
メトリックのdimension既存テンプレートで使われている可能性ありTypeSpec上ではdimensionが2026-05-01-previewでremoved扱いdimension前提のテンプレートや生成コードを棚卸しする

変更の中心はSignalDefinitionの評価ルール

CloudHealthのシグナル定義は、ヘルスモデル内の状態判定に使う信号を定義するリソースです。既存のリファレンスでは、AzureResourceMetric、LogAnalyticsQuery、PrometheusMetricsQueryなどのsignalKindがあり、evaluationRulesでdegradedRuleやunhealthyRuleを設定します。(Microsoft Learn)

v2026-05-01-previewのTypeSpecでは、ThresholdRuleV2に次の変更が入っています。

  • operatorにDynamicが追加される
  • thresholdはfloat64で、2026-05-01-previewから任意扱いになる
  • ただし、ドキュメントコメント上は「静的operatorでは必須、Dynamicでは適用しない」とされている
  • sensitivityは動的しきい値の検出感度として追加される
  • lookBackWindowは動的しきい値計算に使う履歴の参照期間として追加される

この点は実装上かなり重要です。単にthresholdをoptionalにするだけではなく、operatorの値に応じて入力チェックを分ける必要があります。静的なGreaterThanやLessThanでthresholdが欠けている設定は、引き続き不正な設定として扱うべきです。(GitHub)

Dynamic operatorの意味と使いどころ

SignalOperatorには、2026-05-01-previewでDynamic: "Dynamic"が追加されています。説明では、過去のシグナル値の統計的分析を使う動的しきい値とされています。(GitHub)

動的しきい値が向いているのは、固定値では調整しにくいシグナルです。たとえば、CPU使用率、リクエスト数、レイテンシ、ログクエリの集計値などは、時間帯や曜日によって通常値が変わることがあります。固定で「70%を超えたら異常」とすると、ピーク時間帯はアラートが多すぎ、閑散時間帯は異常を見逃す可能性があります。

一方で、動的しきい値は万能ではありません。次のようなシグナルでは、まず固定しきい値のほうが扱いやすい場合があります。

シグナルの例推奨される考え方
ディスク空き容量が10%未満固定しきい値が分かりやすい
エラー率が急増するが平常値に周期性がある動的しきい値を検討しやすい
CPU使用率が業務時間だけ高い動的しきい値の候補
法令・SLA上の明確な基準値がある固定しきい値を優先
データ量が少ない、または履歴が短い動的しきい値は慎重に試す

sensitivityはLow、Medium、Highを目的で選ぶ

DynamicThresholdSensitivityにはLow、Medium、Highが追加されています。TypeSpec上の説明では、Lowは検出される異常が少なくしきい値帯が広め、Mediumはバランス型、Highは検出される異常が多くしきい値帯が狭めという位置づけです。(GitHub)

実務では、最初からHighを本番の重要アラートに使うより、MediumまたはLowで比較検証するほうが安全です。特に、通知先がオンコール担当者やインシデント管理ツールに直結している場合は、検出感度の変更がそのままアラート疲れにつながります。

判断基準は次のように整理できます。

sensitivity向いているケース注意点
Low多少の変動は許容し、明確な異常だけを拾いたい軽微な異常を見逃す可能性がある
Mediumまず標準的に試したい運用データを見て上下に調整する
High小さな変化も早めに検出したいノイズが増えやすいため通知設計が重要

lookBackWindowは「どの履歴を正常とみなすか」の設定

lookBackWindowは、動的しきい値の計算に使う過去データの参照期間です。TypeSpecではISO 8601 duration形式の履歴参照ウィンドウとして説明されています。(GitHub)

短すぎるlookBackWindowは直近の一時的な揺れに引っ張られやすく、長すぎるlookBackWindowは現在の運用状況とずれた古い傾向を含む可能性があります。たとえば、日次バッチの影響を見るなら1日以上、曜日ごとの傾向を見るなら週単位の履歴が候補になります。ただし、正式な許容値や推奨値はサービス側の最新ドキュメントで確認してください。

PR内のサンプルでは、unhealthyRuleにoperator: "Dynamic"、sensitivity: "Medium"、lookBackWindow: "PT7D"を指定する例が掲載されています。サンプル値は実装確認には役立ちますが、実運用では自社の監視対象に合わせて検証する必要があります。(GitHub)

{
  "properties": {
    "metricNamespace": "microsoft.compute/virtualMachines",
    "metricName": "cpuusage",
    "aggregationType": "None",
    "dimensionFilter": "node eq '*'",
    "displayName": "cpu usage",
    "signalKind": "AzureResourceMetric",
    "refreshInterval": "PT1M",
    "timeGrain": "PT1M",
    "dataUnit": "byte",
    "evaluationRules": {
      "degradedRule": {
        "operator": "GreaterThan",
        "threshold": 70
      },
      "unhealthyRule": {
        "operator": "Dynamic",
        "sensitivity": "Medium",
        "lookBackWindow": "PT7D"
      }
    }
  }
}

影響を受けるチームと受けにくいチーム

今回のAzure REST API更新で特に確認が必要なのは、CloudHealthのシグナル定義をコードやテンプレートで管理しているチームです。Azureポータルだけで設定を確認しているチームよりも、REST API、ARMテンプレート、Bicep、Terraform AzAPI、独自の運用ツール、SDK生成コードを使っているチームのほうが影響を受けやすくなります。

対象影響
REST APIを直接呼んでいるアプリapi-version、リクエストbody、レスポンス処理の確認が必要
ARM/Bicep/Terraform AzAPIで管理している環境新フィールドがテンプレート検証で弾かれないか確認が必要
独自のバリデーションを持つ運用ツールthreshold必須チェックとenumチェックの修正が必要
生成SDKを使うアプリSDK側で新APIバージョンや新enumが利用可能か確認が必要
固定しきい値のみを旧APIバージョンで使う環境すぐに変更しなくてもよいが、読み取り処理は新値に備える

PRではAPIViewによるAPIレベルの変更検出が行われ、Swagger、TypeSpec、Go、JavaScript、Python、Java向けのレビューが作成されています。これは、REST API仕様だけでなく、各言語のSDKや生成物にも影響が波及する可能性があることを示しています。(GitHub)

移行前に確認すべき実務ポイント

api-versionを一括で差し替えない

2026-05-01-previewはプレビューAPIバージョンです。既存のCloudHealth設定をすべて新バージョンへ一括移行するのではなく、まずは検証用のHealthModelや一部のSignalDefinitionだけで試すのが安全です。

AutoRest設定では、tag: package-2026-05-01-previewが指定され、新しいcloudhealth.jsonがinput-fileに含まれています。生成系のツールを使っている場合は、このタグを指定したときにどの成果物が出るかを確認してください。(GitHub)

enumを閉じた値として扱わない

SignalOperatorにDynamicが追加されるため、既存コードで次のような実装をしている場合は注意が必要です。

switch (rule.Operator)
{
    case "GreaterThan":
    case "LessThan":
    case "Equal":
        break;
    default:
        throw new NotSupportedException();
}

この実装では、APIからDynamicを含むシグナル定義を読み込んだ時点で失敗します。読み取り処理では未知の値をログに残しつつ保持する、更新処理ではサポート外の値を上書きしない、といった方針が必要です。

thresholdの入力チェックをoperator別にする

よくある失敗は、既存の入力チェックをそのまま使い、thresholdがないという理由だけでDynamicの設定を拒否してしまうことです。新仕様では、thresholdは動的operatorでは適用しないと説明されています。一方で、静的operatorでは必要です。(GitHub)

実装上は、次のような判定に変えると分かりやすくなります。

operatorthresholdsensitivitylookBackWindow
GreaterThanなど静的operator必須不要不要
Dynamic不要任意または運用上指定任意または運用上指定

dimension前提のテンプレートを見直す

TypeSpecでは、ResourceMetricSignalDefinitionPropertiesのdimensionが2026-05-01-previewでremoved扱いになっています。一方で、サンプルではdimensionFilterが使われています。既存テンプレートでdimensionとdimensionFilterをセットで使っている場合は、新バージョンでどの表現に移すべきかを確認してください。(GitHub)

この点は、動的しきい値そのものより見落とされやすい変更です。APIバージョンを上げたあとにテンプレートのデプロイだけが失敗する、生成SDKのプロパティが消える、既存のJSONをそのままPUTできない、といった問題につながる可能性があります。

動的しきい値を本番導入する前のテスト観点

動的しきい値は、固定しきい値よりも運用データとの相性が重要です。設定できるかどうかだけでなく、「期待した異常を拾えるか」「不要な通知が増えないか」を検証してください。

テスト観点確認内容
スキーマ検証Dynamicでthresholdなしのpayloadが通るか
後方互換既存の静的しきい値設定が同じ挙動で維持されるか
GET後の再PUTAPIから取得した新フィールドをツールが削除しないか
enum処理Dynamicを含むレスポンスでアプリが落ちないか
感度調整Low、Medium、Highでアラート数がどう変わるか
履歴期間lookBackWindowを変えたときに検出結果が安定するか
ロールバック旧APIバージョンまたは固定しきい値へ戻す手順があるか

特に重要なのは、GETしたリソースを編集して再PUTする運用ツールです。ツールが知らないプロパティを落として保存すると、sensitivityやlookBackWindowが意図せず消える可能性があります。新APIバージョンに対応するまでは、未知フィールドを保持する設計にしておくと安全です。

すぐに対応すべきチェックリスト

まずは、既存のCloudHealthシグナル定義を棚卸ししてください。すべてを動的しきい値へ変える必要はありません。固定しきい値で問題なく運用できているものは、そのまま維持する判断も十分に合理的です。

  • CloudHealthのsignalDefinitionsを一覧化する
  • api-versionをコード、テンプレート、CI/CD設定から検索する
  • SignalOperatorをswitch文やenumで固定処理している箇所を探す
  • thresholdを常に必須としているバリデーションを確認する
  • dimensionを使っているテンプレートやJSONを確認する
  • 動的しきい値を試す候補シグナルを1〜3個に絞る
  • 重要通知に入れる前に、通知なしまたは低優先度で比較検証する
  • SDK利用環境では、対象言語のSDKが新APIバージョンをサポートしているか確認する

まとめ：まずは仕様確認、次に小さく検証する

Azure REST APIのv2026-05-01-preview追加は、CloudHealthのシグナル定義に動的しきい値を導入するための重要な更新です。固定しきい値では扱いにくい、時間帯や曜日で変動するメトリックに対して有効な選択肢になります。

一方で、対応すべきポイントはoperator: "Dynamic"を追加するだけではありません。thresholdの条件付き必須化、sensitivityとlookBackWindowの扱い、enum処理、IaCテンプレート、SDK生成物、dimension関連の差分まで確認する必要があります。

次に取るべき行動は明確です。まず既存のCloudHealthシグナル定義と利用中のapi-versionを棚卸しし、動的しきい値に向いているシグナルを小さく選んで検証してください。正式ドキュメントやPRの状態を確認しながら、プレビューAPIとして段階的に取り込むのが安全です。

Azure
APIバージョン Azure REST API CloudHealth 動的しきい値

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次