Migrieren von Legacywarnungen zur Warnungs- und Incident-API

Die ältere Api für Microsoft Graph-Sicherheitswarnungen, die über den /security/alerts Endpunkt verfügbar ist, ist veraltet und wird am 31. August 2026 eingestellt. Wenn Ihre App derzeit die Legacywarnungs-API verwendet, um Sicherheitswarnungen abzurufen, zu überwachen oder zu verwalten, sollten Sie zur neuen Api für Warnungen und Vorfälle 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 31. August 2026 gibt der Legacyendpunkt /security/alerts keine Daten mehr zurück. Migrieren Sie Ihre Apps vor diesem Stichtag, um Unterbrechungen ihrer Workflows für Sicherheitsvorgänge zu vermeiden.

  • Die neue Warnungs- und Incidents-API ist kein direkter 1:1-Ersatz für die Legacywarnungs-API. Es werden Warnungen angezeigt, die Teil des Microsoft 365 Defender-Ökosystems sind. Warnungen von 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 abgestimmte 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, Skripts, Connectors und Downstreamprozesse, die aufrufen /security/alerts.
  • Wenn Sie Microsoft Sentinel verwenden, überprüfen Sie, ob Ihr Arbeitsbereich mit dem Microsoft Defender-Portal verbunden ist. 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.

Gründe für die Migration

Die neue Warnungs- und Incidents-API bietet erhebliche Verbesserungen gegenüber der älteren 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: Legacyzustandsauflistungen (userStates, hostStates, fileStates) werden durch mehr als 40 stark typisierte Beweisobjekte wie , azureResourceEvidence, aiAgentEvidenceund analyzedMessageEvidence ersetzt, userEvidencedie programmgesteuert einfacher zu verwenden sind.
  • Incidentorientiertes Modell: Die neue API führt ein erstklassiges Incidentobjekt ein, das den gesamten Angriffsverlauf 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-Risikomanagement.
  • Umfassenderer 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 Legacyendpunkt 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
Abrufen des Incidents nach ID 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
Lese- und Schreibvorfälle API nicht verfügbar SecurityIncident.ReadWrite.All

Nachdem Sie Ihrer App-Registrierung die neuen Berechtigungen 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 Referenz zu Microsoft Graph-Berechtigungen.

Feldzuordnung

In der folgenden Tabelle werden Legacy-Warnungen v1-Felder ihren Warnungen v2-Entsprechungen zugeordnet. Diese Zuordnung deckt nur Felder ab, die in v1 vorhanden sind und eine direkte oder ungefähre Entsprechung in v2 haben. Die neue API enthält viele zusätzliche Felder, die einen umfassenderen Kontext zu Warnungen und Vorfällen bieten.

v1-Feld v2-Feld Hinweise
azureTenantId tenantId Gleiche Bedeutung, eigenschaft umbenannt.
lastModifiedDateTime lastUpdateDateTime Verfolgt den Zeitpunkt der letzten Aktualisierung nach.
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 Ermittlung des Angriffstyps.
vendorInformation.provider serviceSource + productName Anbietermetadaten werden in eine Enumeration und einen Anzeigenamen aufgeteilt.
sourceMaterials[] alertWebUrl + incidentWebUrl Portallinks verweisen jetzt auf die einheitliche Defender-Benutzeroberfläche.
eventDateTime firstActivityDateTime + lastActivityDateTime 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 den Gerätebeweis verschoben.
fileStates[].name / fileHash.hashValue evidence(fileEvidence).fileName/fileDetails.sha256 Dateimetadaten und Hashes werden in Dateibeweis verschoben.
networkConnections[].destinationUrl evidence(urlEvidence).url Netzwerkartefakte zerlegen sich in separate Beweistypen.
networkConnections[].destinationAddress evidence(ipEvidence).ipAddress IP-Adressen werden in IP-Nachweise verschoben.
Konfidenz Kein direkter Ersatz Verwenden Sie Bewertungswerte auf Beweisebene, z. B. verdächtige oder böswillige Werte, anstelle einer numerischen Bewertung.

Migrieren Ihrer App

Führen Sie diese Schritte aus, um von der älteren Warnungs-API zur neuen Warnungs- und Incident-API zu migrieren.

Schritt 1: Identifizieren von Abhängigkeiten

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

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

Wenn Sie Microsoft Sentinel verwenden, verbinden Sie Ihren Arbeitsbereich mit dem Microsoft Defender-Portal, und vergewissern Sie sich, dass relevante Erkennungen zu Incidents heraufgestuft werden. Ohne diese Integration werden Sentinel generierte Warnungen nicht in der v2-API angezeigt.

Verwenden Sie während der Vorbereitung auf das Onboarding 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 wird in Zukunft eingestellt. Priorisieren Sie das Onboarding des Defender-Portals vor dem Stichtag am 31. August 2026.

Weitere Informationen finden Sie unter Verbinden von Microsoft Sentinel mit dem Microsoft Defender-Portal und Umstellen Ihrer Microsoft Sentinel-Umgebung auf das Defender-Portal.

Schritt 3: Aktualisieren von API-Endpunkten und -Berechtigungen

Für jede Integration:

  1. Ersetzen Sie Aufrufe von /security/alerts/security/alerts_v2 durch oder /security/incidents entsprechend Ihrem Workflow.
  2. Aktualisieren Sie die Berechtigungen für die App-Registrierung, und holen Sie die Administratoreinwilligung ein.
  3. Dokumentieren Sie alle Authentifizierungslücken, und beheben Sie sie vor der Einstellungsfrist.

Schritt 4: Aktualisieren Des Datenmodells und der Abfragelogik

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

  • Incidents als erstklassige Objekte behandeln: In v2 gehören Warnungen zu Incidents. Erwägen Sie, Ihren Workflow für Incidents zu erstellen, 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 neu generieren: Aktualisieren Sie Abfragefilter, um die neuen Eigenschaftennamen und die evidence/any() Funktion für die beweisbasierte Filterung zu verwenden.

Die folgenden Beispiele zeigen häufige Filter-Umschreibungen.

Filtern nach Produkt oder Quelle

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

Filtern nach beteiligten Benutzern

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

Filtern nach beteiligten Geräten

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

Incidentorientierte 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 nachgeschalteter Workflows

Bevor Sie Ihre Legacyintegration außer Kraft setzen:

  1. Vergewissern Sie sich, dass erwartete Warnungen und Vorfälle von der neuen API zurückgegeben werden.
  2. Stellen Sie sicher, dass downstream-Workflows wie Automatisierung, Berichterstellung und SIEM-Erfassung nach der Migration ordnungsgemäß funktionieren.
  3. Überprüfen Sie bekannte Abdeckungsunterschiede, 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: Sentinel generierte Warnungen werden von der v2-API nur 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 vorhanden sind – einschließlich eigenständiger Erkennungen, die nicht zu einem Incident heraufgestuft werden – werden von der v2-API nicht zurückgegeben.
  • Abgestimmte Warnungen: Warnungen, die von Warnungsoptimierungsregeln unterdrückt werden, werden nicht über den alerts_v2 Endpunkt zurückgegeben.
  • Low-Signal-Exchange Online-Ereignisse: Bestimmte Exchange Online Ereignisse mit geringem Signal, z. B. erstellung von Postfachregeln und Nachrichtenverzögerungen, sind in alerts_v2nicht enthalten. Rufen Sie diese über Überwachungsprotokolle oder andere relevante Datenquellen ab.

Verwandte Inhalte

  • Last updated on