従来のアラートからアラートとインシデント API への移行

/security/alerts エンドポイントで利用できる従来の Microsoft Graph セキュリティ アラート API は非推奨となり、2026 年 10 月 15 日に廃止される予定です。 現在、アプリで従来のアラート API を使用してセキュリティ アラートを取得、監視、管理している場合は、/security/alerts_v2 エンドポイントから使用できる Microsoft 365 Defender の新しいアラートとインシデント API に移行する必要があります。

この記事では、2 つの API の主な相違点について説明し、フィールド マッピングのリファレンスを提供し、アプリを移行する手順の概要を示します。

重要

  • 2026 年 10 月 15 日以降、レガシ /security/alerts エンドポイントはデータを返さなくなります。 セキュリティ運用のワークフローの中断を回避するには、この期限までにアプリを移行してください。

  • 新しいアラートとインシデント API は、従来のアラート API の直接的な 1 対 1 の置き換え ではありません 。 Microsoft 365 Defender エコシステムの一部であるアラートを表示します。 Microsoft 365 Defender と統合されていないソースからのアラート (Microsoft Microsoft Defender ポータルに接続されていない Microsoft Sentinel ワークスペースやスタンドアロンの調整されたアラートなど) は、新しい API によって返されません。 移行を開始する前に、「 既知の違いと制限事項 」セクションを確認してください。

開始する前に

移行を開始する前に、次のタスクを完了してください。

  • /security/alertsを呼び出すすべての統合、スクリプト、コネクタ、およびダウンストリーム プロセスを識別します。
  • Microsoft Sentinel を使用している場合は、ワークスペースが Microsoft Defender ポータルに接続されているかどうかを確認します。 Sentinel で生成されたアラートは、オンボードが完了するまで v2 API 経由で利用できません。 暫定的に、Sentinel REST APIを使用してSentinelアラートを取得します。 スタンドアロンの Sentinel アラートは v2 API ではサポートされておらず、Sentinel REST API は今後廃止される予定です。
  • 既知の違いと制限事項を確認して、ワークフローで必要となる可能性のある補足データ ソースを特定します。

移行する理由

新しいアラートとインシデント API は、従来のアラート API に比べて大幅に改善されています。

  • 自動相関:ID、エンドポイント、電子メール、クラウドなどの複数のシグナルからのアラートは自動的にインシデントにグループ化され、アナリストは攻撃をより広範囲に把握できます。
  • より豊富な証拠: 従来の状態コレクション (userStates、 hostStates、 fileStates) は、 userEvidence、 azureResourceEvidence、 aiAgentEvidence、 analyzedMessageEvidence など、プログラムで操作しやすい 40 を超える厳密に型指定された証拠オブジェクトに置き換えられます。
  • インシデント中心のモデル: 新しい API では、攻撃の完全なストーリーを表すファースト クラスの インシデント オブジェクトが導入され、より効果的な調査と対応が可能になります。
  • 脅威のカバレッジの拡大: 統合 API には、Microsoft Purview データ損失防止やインサイダー リスク管理などの追加ソースが含まれています。
  • 豊富な脅威コンテキスト: アラートとインシデントには、MITRE ATT&CK 手法、検出ソース、脅威の分類が含まれます。

API の違い

エンドポイント

次の表に、エンドポイントの変更の一覧を示します。

操作 レガシ エンドポイント 新しいエンドポイント
アラートを一覧表示する GET /v1.0/security/alerts GET /v1.0/security/alerts_v2
ID によってアラートを取得する GET /v1.0/security/alerts/{id} GET /v1.0/security/alerts_v2/{id}
アラートを更新する PATCH /v1.0/security/alerts/{id} PATCH /v1.0/security/alerts_v2/{id}
インシデントをリストする 使用不可 GET /v1.0/security/incidents
ID でインシデントを取得する 使用不可 GET /v1.0/security/incidents/{id}

アクセス許可

アプリの登録を新しい Microsoft Graph アクセス許可範囲で更新する必要があります。

シナリオ 従来のアクセス許可 新しいアクセス許可
アラートを読み取る SecurityEvents.Read.All SecurityAlert.Read.All
警告の読み取りと書き込み SecurityEvents.ReadWrite.All SecurityAlert.ReadWrite.All
インシデントの読み取り API は利用できません SecurityIncident.Read.All
インシデントの読み取りと書き込み API は利用できません SecurityIncident.ReadWrite.All

アプリ登録に新しいアクセス許可を追加した後、アプリが運用環境で使用する前に管理者が同意する必要があります。

これらのアクセス許可の詳細については、「 Microsoft Graph のアクセス許可リファレンス」を参照してください。

フィールドのマッピング

次の表に、従来の アラート v1 のフィールドを対応する アラート v2 のフィールドにマップします。 このマッピングは、v1 に存在し、v2 に直接的または近似的に対応するフィールドのみを対象とします。 新しい API には、アラートとインシデントに関する豊富なコンテキストを提供する多くの追加フィールドが含まれています。

v1 フィールド V2 フィールド 備考
azureTenantId tenantId 同じ意味ですが、プロパティの名前が変更されました。
lastModifiedDateTime lastUpdateDateTime 最新の更新時間を追跡します。
closedDateTime resolvedDateTime アラートが解決された時期を表します。
activityGroupName actorDisplayName アクター コンテキストのフィールドの名前が変更されました。
feedback 分類+判定 V2 では、ディスポジションと攻撃の種類の判定が分離されています。
vendorInformation.provider serviceSource + productName プロバイダーのメタデータは、列挙型と表示名に分割されます。
sourceMaterials[] alertWebUrl + incidentWebUrl ポータル リンクが統合 Defender エクスペリエンスを指すようになりました。
eventDateTime firstActivityDateTime + lastActivityDateTime 1 つのタイムスタンプが時間範囲になります。
incidentIds[] incidentId 各アラートは、正確に 1 つのインシデントに属します。
userStates[].userPrincipalName evidence(userEvidence).userAccount.userPrincipalName ユーザー エンティティは、型指定された証拠オブジェクトに移動します。
hostStates[].fqdn evidence(deviceEvidence).deviceDnsName ホスト情報はデバイス証拠に移動します。
fileStates[].name / fileHash.hashValue evidence(fileEvidence).fileName / fileDetails.sha256 ファイル メタデータとハッシュは、ファイル証拠に移動します。
networkConnections[].destinationUrl evidence(urlEvidence).url ネットワーク アーティファクトは、個別の証拠の種類に分解されます。
networkConnections[].destinationAddress evidence(ipEvidence).ipAddress IP アドレスは IP 証拠に移動します。
信頼度 直接置換はありません 数値スコアの代わりに、疑わしい、悪意のあるなどの証拠レベルの判定値を使用します。

アプリの移行

レガシ アラート API から新しいアラートおよびインシデント API に移行するには、次の手順を使用します。

手順 1: 依存関係を特定する

コードを変更する前に、現在 /security/alerts を呼び出しているすべての統合、スクリプト、コネクタ、およびダウンストリーム プロセスを識別します。

手順 2: Microsoft Sentinel を接続して可視性を統合する

Microsoft Sentinel を使用している場合は、ワークスペースを Microsoft Defender ポータルに接続し、関連する検出がインシデントに昇格されることを確認します。 この統合を使用しない場合、Sentinelで生成されたアラートはv2 APIに表示されません。

オンボーディングの準備中に、Sentinel REST APIを使用してSentinelアラートを取得します。 スタンドアロンのSentinelアラートは新しいAPIモデルではサポートされておらず、Sentinel REST APIは今後廃止されることに注意してください。 2026 年 10 月 15 日の期限より前に、Defender ポータルのオンボードを優先します。

詳細については、「Microsoft Sentinel を Microsoft Defender ポータルに接続する」および「Microsoft Sentinel 環境を Defender ポータルに移行する」を参照してください。

手順 3: API エンドポイントとアクセス許可を更新する

各統合の場合:

  1. ワークフローに応じて、 /security/alerts への呼び出しを /security/alerts_v2 または /security/incidents に置き換えます。
  2. アプリ登録アクセス許可を更新し、管理者の同意を取得します。
  3. 認証のギャップを文書化し、廃止期限の前に解決します。

手順 4: データ モデルとクエリ ロジックを更新する

v2 移行に必要なのは、フィールド間のスワップ以上のものです。 次の変更を計画します。

  • インシデントをファースト クラス オブジェクトとして扱う: v2 では、アラートはインシデントに属します。 攻撃の完全なストーリーを把握するために、インシデントを中心にワークフローを構築することを検討してください。
  • 解析とエンリッチメントのロジックを更新する: userStates、 hostStates、 fileStates、 networkConnections への参照を、対応する型指定された証拠オブジェクトに置き換えます。
  • OData フィルターを書き換える: 新しいプロパティ名と evidence/any() 関数を使用して、証拠ベースのフィルター処理を行うようにクエリ フィルターを更新します。

次の例は、一般的なフィルター書き換えを示しています。

製品またはソースでフィルター処理

# Legacy
GET /v1.0/security/alerts?$filter=vendorInformation/provider eq 'Microsoft Defender ATP'

# New - alerts v2
GET /v1.0/security/alerts_v2?$filter=serviceSource eq 'microsoftDefenderForEndpoint'

関与するユーザーでフィルター

# Legacy: No direct OData filter on userStates sub-properties; required client-side filtering.

# New - alerts v2
GET /v1.0/security/alerts_v2?$filter=evidence/any(e: e/microsoft.graph.security.userEvidence/userAccount/userPrincipalName eq 'alice@contoso.com')

関連するデバイスでフィルター処理

# Legacy
GET /v1.0/security/alerts?$filter=hostStates/any(h: h/fqdn eq 'pc123.contoso.com')

# New
GET /v1.0/security/alerts_v2?$filter=evidence/any(e: e/microsoft.graph.security.deviceEvidence/deviceDnsName eq 'pc123.contoso.com')

インシデント中心のクエリ (新機能)

# Get all active, high-severity incidents
GET /v1.0/security/incidents?$filter=status eq 'active' and severity eq 'high'

# Get all alerts for a specific incident
GET /v1.0/security/incidents/{incidentId}/alerts

手順 5: カバレッジとダウンストリーム ワークフローを検証する

レガシ統合を廃止する前に:

  1. 新しい API によって、予期されたアラートとインシデントが返されることを確認します。
  2. 移行後、自動化、レポート、SIEM 取り込みなどのダウンストリーム ワークフローが正しく機能することを確認します。
  3. 既知のカバレッジの違いを確認し、まだ必要な補足データ ソースを特定します。

Graph エクスプローラーなどの API テスト ツールを使用して、クエリを検証し、新しいデータ モデルを検査します。

既知の違いと制限事項

  • Microsoft Sentinel の対象範囲: Sentinel ワークスペースが Microsoft Defender ポータルに接続されていない限り、Sentinel で生成されたアラートは v2 API によって返されません。 暫定的に、Sentinel REST APIを使用してこれらのアラートを取得します。
  • スタンドアロン アラート: Microsoft 365 Defender インシデント モデルの外部に存在するアラート (インシデントに昇格されていないスタンドアロンの検出を含む) は、v2 API によって返されません。
  • 調整されたアラート: アラート調整ルールによって抑制されたアラートは、 alerts_v2 エンドポイントからは返されません。
  • 低信号Exchange Online イベント: メールボックス ルールの作成やメッセージの遅延など、特定の低信号Exchange Online イベントは alerts_v2 に含まれません。 これらは、監査ログまたはその他の関連するデータ ソースから取得します。

関連コンテンツ

  • Last updated on