Переход с устаревших оповещений на API оповещений и инцидентов

Устаревший API оповещений системы безопасности Microsoft Graph, доступный через конечную точку /security/alerts , устарел и будет прекращен 31 августа 2026 г. Если в настоящее время приложение использует устаревший API оповещений для получения, мониторинга оповещений системы безопасности и управления ими, следует перейти на новый API оповещений и инцидентов в Microsoft 365 Defender, доступный через конечную точку /security/alerts_v2 .

В этой статье описаны основные различия между двумя API, приведен справочник по сопоставлению полей и описаны шаги по миграции приложения.

Важно!

  • После 31 августа 2026 г. устаревшая конечная /security/alerts точка перестанет возвращать данные. Перенесите приложения до этого крайнего срока, чтобы избежать прерывания рабочих процессов операций безопасности.

  • Новый API оповещений и инцидентов не является прямой заменой api оповещений прежних версий. Он предоставляет оповещения, которые являются частью экосистемы Microsoft 365 Defender. Оповещения из источников, которые не интегрированы с Microsoft 365 Defender, например рабочей области Microsoft Sentinel, не подключенной к порталу Microsoft Defender, или автономных и настроенных оповещений, не возвращаются новым API. Прежде чем начинать миграцию, ознакомьтесь с разделом известных различий и ограничений .

Подготовка к работе

Перед началом миграции выполните следующие задачи:

  • Определите все интеграции, скрипты, соединители и подчиненные процессы, которые вызывают /security/alerts.
  • Если вы используете Microsoft Sentinel, проверьте, подключена ли рабочая область к порталу Microsoft Defender. оповещения, созданные Sentinel, недоступны через API версии 2, пока вы не завершите подключение. Для получения оповещений Sentinel используйте REST API Sentinel. Автономные оповещения Sentinel не поддерживаются в API версии 2, и в будущем Sentinel REST API будет прекращен.
  • Просмотрите известные различия и ограничения , чтобы определить дополнительные источники данных, которые могут потребоваться рабочим процессам.

Зачем выполнять миграцию?

Новый API оповещений и инцидентов предлагает значительные улучшения по сравнению с устаревшим API оповещений:

  • Автоматическая корреляция. Оповещения от нескольких сигналов (удостоверения, конечной точки, электронной почты и облака) автоматически группируются в инциденты, предоставляя аналитикам более широкое представление об атаке.
  • Более богатые доказательства. Устаревшие коллекции состояний (userStates, hostStates, fileStates) заменяются более чем 40 строго типизированными объектами доказательства, такими как userEvidence, azureResourceEvidence, aiAgentEvidenceи analyzedMessageEvidence , с которыми проще работать программно.
  • Модель, ориентированная на инциденты. Новый API представляет первоклассный объект инцидента , который представляет полную историю атаки, обеспечивая более эффективное расследование и реагирование.
  • Расширенный охват угроз. Единый API включает дополнительные источники, такие как Защита от потери данных Microsoft Purview и управление внутренними рисками.
  • Более широкий контекст угроз. Оповещения и инциденты включают MITRE ATT&методов CK, источников обнаружения и классификации угроз.

Различия API

Конечные точки

В следующей таблице перечислены изменения конечной точки.

Operation Устаревшая конечная точка Новая конечная точка
Перечисление оповещений GET /v1.0/security/alerts GET /v1.0/security/alerts_v2
Получение оповещений по идентификатору 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
Получение инцидента по идентификатору Недоступно 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.

Сопоставление полей

В следующей таблице поля устаревших оповещений версии 1 сопоставлены с их эквивалентами оповещений версии 2 . Это сопоставление охватывает только поля, которые существуют в версии 1 и имеют прямой или приблизительный аналог в версии 2. Новый API включает множество дополнительных полей, которые обеспечивают расширенный контекст оповещений и инцидентов.

Поле версии 1 Поле версии 2 Примечания
azureTenantId tenantId То же значение, переименованное свойство.
lastModifiedDateTime lastUpdateDateTime Отслеживает время последнего обновления.
closedDateTime resolvedDateTime Представляет время разрешения оповещения.
activityGroupName actorDisplayName Переименованное поле для контекста субъекта.
feedback классификация и определение Версия 2 отделяет ликвидацию от определения типа атаки.
vendorInformation.provider serviceSource + productName Метаданные поставщика делятся на перечисление и отображаемое имя.
sourceMaterials[] alertWebUrl + incidentWebUrl Ссылки на портал теперь указывают на единый интерфейс Defender.
eventDateTime firstActivityDateTime + lastActivityDateTime Одна метка времени становится диапазоном времени.
incidentIds[] incidentId Теперь каждое оповещение относится только к одному инциденту.
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, не отображаются в API версии 2.

Во время подготовки к подключению используйте REST API Sentinel для получения оповещений Sentinel. Имейте в виду, что автономные оповещения Sentinel не поддерживаются в новой модели API, и в будущем Sentinel REST API будет прекращен. Приоритезируйте подключение портала Defender до крайнего срока 31 августа 2026 г.

Дополнительные сведения см. в разделах Подключение Microsoft Sentinel к порталу Microsoft Defender и Переход среды Microsoft Sentinel на портал Defender.

Шаг 3. Обновление конечных точек и разрешений API

Для каждой интеграции:

  1. Замените вызовы на /security/alerts или /security/incidents в соответствии с /security/alerts_v2 вашим рабочим процессом.
  2. Обновите разрешения на регистрацию приложений и получите согласие администратора.
  3. Задокументируйте все пробелы проверки подлинности и устраните их до крайнего срока прекращения использования.

Шаг 4. Обновление модели данных и логики запросов

Для миграции версии 2 требуется не просто переключение поля на поле. Запланируйте следующие изменения:

  • Обрабатывать инциденты как объекты первого класса. В версии 2 оповещения относятся к инцидентам. Рассмотрите возможность создания рабочего процесса вокруг инцидентов, чтобы получить полную историю атаки.
  • Обновление логики синтаксического анализа и обогащения. Замените ссылки на 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. Просмотрите известные различия в охвате и определите все необходимые дополнительные источники данных.

Используйте средство тестирования API, например Graph Обозреватель, чтобы проверить запросы и проверить новую модель данных.

Известные различия и ограничения

  • Microsoft Sentinel покрытия: API версии 2 не возвращает созданные Sentinel оповещения, если ваша рабочая область Sentinel не подключена к порталу Microsoft Defender. Для получения этих оповещений используйте REST API Sentinel.
  • Автономные оповещения. Api версии 2 не возвращает оповещения, существующие за пределами модели инцидентов Microsoft 365 Defender, включая автономные обнаружения, которые не были повышены до инцидента.
  • Настроенные оповещения. Оповещения, подавляемые правилами настройки оповещений, не возвращаются через конечную точку alerts_v2 .
  • События Exchange Online с низким сигналом. Некоторые события Exchange Online с низким уровнем сигнала, такие как создание правила почтового ящика и задержки сообщений, не включаются в alerts_v2. Получите их с помощью журналов аудита или других соответствующих источников данных.

Связанные материалы

  • Last updated on