/security/alerts エンドポイントで使用できる従来の Microsoft Graph セキュリティ アラート API は非推奨となり、2026 年 8 月 31 日に廃止されます。 現在、アプリでレガシ アラート API を使用してセキュリティ アラートを取得、監視、または管理している場合は、microsoft 365 Defender の新しい アラートとインシデント API ( /security/alerts_v2 エンドポイントを通じて利用可能) に移行する必要があります。
この記事では、2 つの API の主な違いについて説明し、フィールド マッピング リファレンスを提供し、アプリを移行する手順について説明します。
重要
2026 年 8 月 31 日以降、レガシ
/security/alertsエンドポイントはデータの返しを停止します。 セキュリティ運用ワークフローの中断を回避するために、この期限前にアプリを移行します。新しいアラートとインシデント API は、従来のアラート API の直接的な 1 対 1 の置き換え ではありません 。 Microsoft 365 Defender エコシステムの一部であるアラートが表示されます。 Microsoft 365 Defender と統合されていないソースからのアラート (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 データ損失防止や Insider Risk Management などの追加のソースが含まれています。
- よりリッチな脅威コンテキスト: アラートとインシデントには、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 年 8 月 31 日の期限を前に、Defender ポータルのオンボードを優先します。
詳細については、「Microsoft Defender ポータルにMicrosoft Sentinelを接続する」および「Microsoft Sentinel環境を Defender ポータルに移行する」を参照してください。
手順 3: API エンドポイントとアクセス許可を更新する
統合ごとに次の手順を実行します。
-
/security/alertsの呼び出しを、ワークフローに応じて/security/alerts_v2または/security/incidentsに置き換えます。 - アプリ登録のアクセス許可を更新し、管理者の同意を得る。
- 認証ギャップを文書化し、廃止期限の前に解決します。
手順 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: カバレッジとダウンストリーム ワークフローを検証する
レガシ統合を廃止する前に、次の手順を実行します。
- 予想されるアラートとインシデントが新しい API によって返されることを確認します。
- 自動化、レポート、SIEM インジェストなどのダウンストリーム ワークフローが移行後に正しく機能することを確認します。
- 既知のカバレッジの違いを確認し、引き続き必要な補足データ ソースを特定します。
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に含まれません。 監査ログまたはその他の関連データ ソースを使用してこれらを取得します。