Migrieren von Legacywarnungen zur Warnungs- und Vorfalls-API

Die veraltete Microsoft Graph-Sicherheitswarnungs-API, die über den /security/alerts Endpunkt verfügbar war, ist veraltet und wird am 15. Oktober 2026 eingestellt. Wenn Ihre App derzeit die veraltete Warnungs-API zum Abrufen, Überwachen oder Verwalten von Sicherheitswarnungen verwendet, sollten Sie zur neuen Warnungs- und Vorfall-API in Microsoft 365 Defender migrieren, die über den /security/alerts_v2 Endpunkt verfügbar ist.

In diesem Artikel werden die wichtigsten Unterschiede zwischen den beiden APIs beschrieben, eine Feldzuordnungsreferenz bereitgestellt und die Schritte zum Migrieren Ihrer App beschrieben.

Wichtig

  • Nach dem 15. Oktober 2026 gibt der Legacyendpunkt /security/alerts keine Daten mehr zurück. Migrieren Sie Ihre Apps vor diesem Stichtag, um Unterbrechungen Ihrer Sicherheitsabläufe zu vermeiden.

  • Die neue Warnungs- und Vorfall-API ist kein direkter 1:1-Ersatz für die alte Warnungs-API. Es zeigt Warnungen an, die Teil des Microsoft 365 Defender-Ökosystems sind. Warnungen aus Quellen, die nicht in Microsoft 365 Defender integriert sind, z. B. ein Microsoft Sentinel-Arbeitsbereich, der nicht mit dem Microsoft Defender-Portal verbunden ist, oder eigenständige und optimierte Warnungen, werden von der neuen API nicht zurückgegeben. Lesen Sie den Abschnitt "Bekannte Unterschiede und Einschränkungen", bevor Sie mit der Migration beginnen.

Bevor Sie beginnen

Bevor Sie mit der Migration beginnen, führen Sie die folgenden Aufgaben aus:

  • Identifizieren Sie alle Integrationen, Skripte, Connectors und Downstreamprozesse, die /security/alerts.
  • Wenn Sie Microsoft Sentinel verwenden, überprüfen Sie, ob Ihr Arbeitsbereich mit dem Microsoft Defender-Portal verbunden ist. Von Sentinel generierte Warnungen sind erst über die v2-API verfügbar, wenn Sie das Onboarding abgeschlossen haben. Verwenden Sie in der Zwischenzeit die Sentinel-REST-API, um Sentinel-Warnungen abzurufen. Eigenständige Sentinel-Warnungen werden in der v2-API nicht unterstützt, und die Sentinel-REST-API wird in Zukunft eingestellt.
  • Überprüfen Sie die bekannten Unterschiede und Einschränkungen , um zusätzliche Datenquellen zu identifizieren, die für Ihre Workflows möglicherweise erforderlich sind.

Warum migrieren?

Die neue Warnungs- und Incidents-API bietet erhebliche Verbesserungen gegenüber der veralteten Warnungs-API:

  • Automatische Korrelation: Warnungen von mehreren Signalen – Identität, Endpunkt, E-Mail und Cloud – werden automatisch in Incidents gruppiert, sodass Analysten einen umfassenderen Überblick über einen Angriff erhalten.
  • Umfangreichere Beweise: Ältere Zustandssammlungen (userStates, hostStates, fileStates) werden durch mehr als 40 stark typisierte Beweisobjekte ersetzt, z. B userEvidence. , azureResourceEvidence, aiAgentEvidence, und analyzedMessageEvidence mit denen programmgesteuert einfacher gearbeitet werden kann.
  • Incident-zentriertes Modell: Die neue API führt ein erstklassiges Incident-Objekt ein, das die gesamte Angriffsgeschichte darstellt und eine effektivere Untersuchung und Reaktion ermöglicht.
  • Erweiterte Bedrohungsabdeckung: Die einheitliche API umfasst zusätzliche Quellen wie Microsoft Purview Data Loss Prevention und Insider Risk Management.
  • Umfangreicherer Bedrohungskontext: Warnungen und Vorfälle umfassen MITRE ATT-&CK-Techniken, Erkennungsquellen und Bedrohungsklassifizierung.

API-Unterschiede

Endpunkte

In der folgenden Tabelle sind die Endpunktänderungen aufgeführt.

Vorgang Legacy-Endpunkt Neuer Endpunkt
Warnungen auflisten GET /v1.0/security/alerts GET /v1.0/security/alerts_v2
Warnung nach ID abrufen GET /v1.0/security/alerts/{id} GET /v1.0/security/alerts_v2/{id}
Warnung aktualisieren PATCH /v1.0/security/alerts/{id} PATCH /v1.0/security/alerts_v2/{id}
Auflisten von Vorfällen Nicht verfügbar GET /v1.0/security/incidents
Incident nach ID abrufen Nicht verfügbar GET /v1.0/security/incidents/{id}

Berechtigungen

Ihre App-Registrierung muss mit neuen Microsoft Graph-Berechtigungsbereichen aktualisiert werden.

Szenario Legacyberechtigung Neue Berechtigung
Lesezugriff auf Warnungen SecurityEvents.Read.All SecurityAlert.Read.All
Lese- und Schreibwarnungen SecurityEvents.ReadWrite.All SecurityAlert.ReadWrite.All
Lesen von Vorfällen API nicht verfügbar SecurityIncident.Read.All
Vorfälle beim Lesen und Schreiben API nicht verfügbar SecurityIncident.ReadWrite.All

Nachdem Sie die neuen Berechtigungen Ihrer App-Registrierung hinzugefügt haben, muss ein Administrator die Zustimmung erteilen, bevor die App sie in der Produktion verwenden kann.

Weitere Informationen zu diesen Berechtigungen finden Sie in der Microsoft Graph-Berechtigungsreferenz.

Feldzuordnung

In der folgenden Tabelle werden die Felder der Legacywarnungen v1 den entsprechenden Warnungen v2 zugeordnet. Diese Zuordnung deckt nur Felder ab, die in v1 vorhanden sind und ein direktes oder ungefähres Gegenstück in v2 haben. Die neue API enthält viele zusätzliche Felder, die einen ausführlicheren Kontext zu Warnungen und Incidents bereitstellen.

v1-Feld v2-Feld Hinweise
azureTenantId tenantId Die gleiche Bedeutung, umbenanntes Eigentum.
lastModifiedDateTime lastUpdateDateTime Verfolgt den Zeitpunkt der letzten Aktualisierung.
closedDateTime resolvedDateTime Gibt an, wann die Warnung aufgelöst wurde.
activityGroupName actorDisplayName Feld für Akteurkontext umbenannt.
Feedback Klassifizierung + Bestimmung v2 trennt die Disposition von der Bestimmung des Angriffstyps.
vendorInformation.provider serviceSource + productName Anbietermetadaten werden in eine Aufzählung und einen Anzeigenamen aufgeteilt.
sourceMaterials[] alertWebUrl + incidentWebUrl Portallinks verweisen jetzt auf die einheitliche Defender-Erfahrung.
eventDateTime firstActivityDateTime + lastActivityDateTime Ein einzelner Zeitstempel wird zu einem Zeitbereich.
incidentIds[] incidentId Jede Warnung gehört jetzt zu genau einem Incident.
userStates[].userPrincipalName evidence(userEvidence).userAccount.userPrincipalName Benutzerentitäten werden in typisierte Beweisobjekte verschoben.
hostStates[].fqdn evidence(deviceEvidence).deviceDnsName Hostinformationen werden in Gerätebeweismittel verschoben.
fileStates[].name / fileHash.hashValue evidence(fileEvidence).fileName / fileDetails.sha256 Dateimetadaten und Hashes werden in Dateibeweismittel verschoben.
networkConnections[].destinationUrl Beweis (urlBeweis).url Netzwerkartefakte zerlegen sich in separate Beweistypen.
networkConnections[].destinationAddress evidence(ipEvidence).ipAddress IP-Adressen werden zu IP-Beweismitteln.
Konfidenz Kein direkter Ersatz Verwenden Sie Urteilswerte auf Beweisebene, wie verdächtig oder böswillig, anstelle einer numerischen Bewertung.

Migrieren Ihrer App

Führen Sie die folgenden Schritte aus, um von der API für ältere Warnungen zur neuen API für Warnungen und Incidents zu migrieren.

Schritt 1: Identifizieren von Abhängigkeiten

Bevor Sie Code ändern, identifizieren Sie alle Integrationen, Skripte, Connectors und Downstreamprozesse, die derzeit /security/alerts.

Schritt 2: Verbinden von Microsoft Sentinel für einheitliche Transparenz

Wenn Sie Microsoft Sentinel verwenden, verbinden Sie Ihren Arbeitsbereich mit dem Microsoft Defender-Portal, und bestätigen Sie, dass relevante Entdeckungen zu Incidents hochgestuft werden. Ohne diese Integration werden von Sentinel generierte Warnungen nicht in der v2-API angezeigt.

Während Sie sich auf das Onboarding vorbereiten, verwenden Sie die Sentinel-REST-API, um Sentinel-Warnungen abzurufen. Beachten Sie, dass eigenständige Sentinel-Warnungen im neuen API-Modell nicht unterstützt werden und die Sentinel-REST-API in Zukunft eingestellt wird. Priorisieren Sie das Onboarding des Defender-Portals vor dem Stichtag am 15. Oktober 2026.

Weitere Informationen finden Sie unter Verbinden von Microsoft Sentinel mit dem Microsoft Defender-Portal und Übergang Ihrer Microsoft Sentinel-Umgebung zum Defender-Portal.

Schritt 3: Aktualisieren von API-Endpunkten und -Berechtigungen

Für jede Integration:

  1. Ersetzen Sie Anrufe durch /security/alerts/security/alerts_v2 oder /security/incidents nach Bedarf für Ihren Workflow.
  2. Aktualisieren Sie die Berechtigungen für die App-Registrierung, und holen Sie die Administratorzustimmung ein.
  3. Dokumentieren Sie alle Authentifizierungslücken und beheben Sie diese vor Ablauf der Einstellung.

Schritt 4: Aktualisieren des Datenmodells und der Abfragelogik

Die v2-Migration erfordert mehr als einen Feld-für-Feld-Austausch. Planen Sie die folgenden Änderungen ein:

  • Behandeln von Incidents als erstklassige Objekte: In v2 gehören Warnungen zu Incidents. Erwägen Sie, Ihren Workflow um Vorfälle herum aufzubauen, um die vollständige Angriffsgeschichte zu erhalten.
  • Aktualisieren der Analyse- und Anreicherungslogik: Ersetzen Sie Verweise auf userStates, hostStates, fileStatesund networkConnections durch die entsprechenden typisierten Beweisobjekte.
  • OData-Filter umschreiben: Aktualisieren Sie Abfragefilter, um die neuen Eigenschaftsnamen und die evidence/any() Funktion für die evidenzbasierte Filterung zu verwenden.

Die folgenden Beispiele zeigen gängige Filterumschreibungen.

Nach Produkt oder Quelle filtern

# 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'

Nach beteiligtem Benutzer filtern

# 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')

Nach betroffenem Gerät filtern

# 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')

Incidentzentrierte Abfragen (neue Funktion)

# 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

Schritt 5: Überprüfen der Abdeckung und nachgelagerter Workflows

Bevor Sie Ihre Legacyintegration einstellen:

  1. Vergewissern Sie sich, dass die erwarteten Warnungen und Vorfälle von der neuen API zurückgegeben werden.
  2. Stellen Sie sicher, dass nachgelagerte Workflows wie Automatisierung, Berichterstellung und SIEM-Erfassung nach der Migration ordnungsgemäß funktionieren.
  3. Überprüfen Sie bekannte Unterschiede in der Abdeckung und identifizieren Sie alle zusätzlichen Datenquellen, die Sie noch benötigen.

Verwenden Sie ein API-Testtool wie Graph Explorer, um Ihre Abfragen zu überprüfen und das neue Datenmodell zu überprüfen.

Bekannte Unterschiede und Einschränkungen

  • Microsoft Sentinel-Abdeckung: Von Sentinel generierte Warnungen werden von der v2-API nur dann zurückgegeben, wenn Ihr Sentinel-Arbeitsbereich mit dem Microsoft Defender-Portal verbunden ist. Verwenden Sie in der Zwischenzeit die Sentinel-REST-API, um diese Warnungen abzurufen.
  • Eigenständige Warnungen: Warnungen, die außerhalb des Microsoft 365 Defender-Incidentmodells existieren – einschließlich eigenständiger Erkennungen, die nicht zu einem Incident heraufgestuft wurden – werden von der v2-API nicht zurückgegeben.
  • Optimierte Warnungen: Warnungen, die durch Regeln zur Warnungsoptimierung unterdrückt werden, werden nicht über den alerts_v2 Endpunkt zurückgegeben.
  • Exchange Online-Ereignisse mit geringem Signal: Bestimmte Exchange Online-Ereignisse mit geringem Signal, wie z. B. das Erstellen von Postfachregeln und Nachrichtenverzögerungen, sind in nicht enthaltenalerts_v2. Rufen Sie diese über Überwachungsprotokolle oder andere relevante Datenquellen ab.

Verwandte Inhalte

  • Last updated on