Migrar de alertas herdados para a API de alertas e incidentes

A API de alertas de segurança herdada do Microsoft Graph disponível por meio do ponto de extremidade foi preterida /security/alerts e será desativada em 15 de outubro de 2026. Se o seu aplicativo usa atualmente a API de alertas herdados para recuperar, monitorar ou gerenciar alertas de segurança, você deve migrar para a nova API de alertas e incidentes no Microsoft 365 Defender, disponível por meio do ponto de /security/alerts_v2 extremidade.

Este artigo descreve as principais diferenças entre as duas APIs, fornece uma referência de mapeamento de campo e descreve as etapas para migrar seu aplicativo.

Importante

  • Após 15 de outubro de 2026, o ponto de extremidade herdado /security/alerts deixará de retornar dados. Migre seus aplicativos antes desse prazo para evitar interrupções nos fluxos de trabalho de operações de segurança.

  • A nova API de alertas e incidentes não é uma substituição direta e individual da API de alertas herdada. Ele exibe alertas que fazem parte do ecossistema do Microsoft 365 Defender. Alertas de fontes que não estão integradas ao Microsoft 365 Defender, como um espaço de trabalho do Microsoft Sentinel que não está conectado ao portal do Microsoft Defender ou alertas autônomos e ajustados, não são retornados pela nova API. Examine a seção de diferenças e limitações conhecidas antes de iniciar sua migração.

Antes de começar

Antes de iniciar a migração, conclua as seguintes tarefas:

  • Identifique todas as integrações, scripts, conectores e processos downstream que chamam /security/alerts.
  • Se você usar o Microsoft Sentinel, verifique se o seu espaço de trabalho está conectado ao portal do Microsoft Defender. Os alertas gerados pelo Sentinel não estão disponíveis por meio da API v2 até que você conclua essa integração. Enquanto isso, use a API REST do Sentinel para recuperar alertas do Sentinel. Não há suporte para alertas autônomos do Sentinel na API v2 e a API REST do Sentinel será desativada no futuro.
  • Revise as diferenças e limitações conhecidas para identificar quaisquer fontes de dados complementares que seus fluxos de trabalho possam exigir.

Por que migrar?

A nova API de alertas e incidentes oferece melhorias significativas em relação à API de alertas herdada:

  • Correlação automática: alertas de vários sinais (identidade, endpoint, e-mail e nuvem) são agrupados automaticamente em incidentes, dando aos analistas uma visão mais ampla de um ataque.
  • Evidências mais ricas: as coleções de estado herdadas (userStates, hostStates, fileStates) são substituídas por mais de 40 objetos de evidência fortemente tipados, como userEvidence, azureResourceEvidence, aiAgentEvidence, e analyzedMessageEvidence que são mais fáceis de trabalhar programaticamente.
  • Modelo centrado em incidentes: a nova API apresenta um objeto de incidente de primeira classe que representa a história completa do ataque, permitindo investigação e resposta mais eficazes.
  • Cobertura expandida de ameaças: a API unificada inclui fontes adicionais, como a Prevenção Contra Perda de Dados do Microsoft Purview e o Gerenciamento de Risco Interno.
  • Contexto de ameaças mais avançado: alertas e incidentes incluem técnicas MITRE ATT&CK, fontes de detecção e classificação de ameaças.

Diferenças de API

Pontos de extremidade

A tabela a seguir lista as alterações do ponto de extremidade.

Operação Ponto de extremidade herdado Novo ponto de extremidade
Listar alertas GET /v1.0/security/alerts GET /v1.0/security/alerts_v2
Receber alerta por ID GET /v1.0/security/alerts/{id} GET /v1.0/security/alerts_v2/{id}
Atualizar alerta PATCH /v1.0/security/alerts/{id} PATCH /v1.0/security/alerts_v2/{id}
Listar incidentes Não disponível GET /v1.0/security/incidents
Obter incidente por ID Não disponível GET /v1.0/security/incidents/{id}

Permissões

O registro do seu aplicativo deve ser atualizado com novos escopos de permissão do Microsoft Graph.

Cenário Permissão herdada Nova permissão
Ler alertas SecurityEvents.Read.All SecurityAlert.Read.All
Alertas de leitura e gravação SecurityEvents.ReadWrite.All SecurityAlert.ReadWrite.All
Ler incidentes API não disponível SecurityIncident.Read.All
Incidentes de leitura e gravação API não disponível SecurityIncident.ReadWrite.All

Depois de adicionar as novas permissões ao registro do aplicativo, um administrador deve conceder consentimento antes que o aplicativo possa usá-las na produção.

Para obter mais informações sobre essas permissões, consulte a referência de permissões do Microsoft Graph.

Mapeamento de campo

A tabela a seguir mapeia campos de alertas herdados v1 para seus equivalentes de alertas v2 . Esse mapeamento abrange apenas campos que existem na v1 e têm uma contraparte direta ou aproximada na v2. A nova API inclui muitos campos adicionais que fornecem um contexto mais avançado sobre alertas e incidentes.

campo v1 campo v2 Observações
azureTenantId tenantId Mesmo significado, propriedade renomeada.
lastModifiedDateTime lastUpdateDateTime Controla a hora da última atualização.
closedDateTime resolvedDateTime Representa quando o alerta foi resolvido.
activityGroupName actorDisplayName Campo renomeado para contexto de ator.
comentários Classificação + Determinação v2 separa a disposição da determinação do tipo de ataque.
vendorInformation.provider serviceSource + productName Os metadados do provedor são divididos em uma enumeração e um nome de exibição.
sourceMaterials alertWebUrl + incidentWebUrl Os links do portal agora apontam para a experiência unificada do Defender.
eventDateTime firstActivityDateTime + lastActivityDateTime Um carimbo de data/hora único torna-se um intervalo de tempo.
incidentIds[] incidentId Cada alerta agora pertence a exatamente um incidente.
userStates[].userPrincipalName evidence(userEvidence).userAccount.userPrincipalName As entidades de usuário se movem para objetos de evidência tipados.
hostStates[].fqdn evidence(deviceEvidence).deviceDnsName As informações do host se movem para a evidência do dispositivo.
fileStates[].name / fileHash.hashValue evidence(fileEvidence).fileName / fileDetails.sha256 Os metadados e hashes de arquivo são movidos para evidências de arquivo.
networkConnections[].destinationUrl evidence(urlEvidence).url Os artefatos de rede se decompõem em tipos de evidência separados.
networkConnections[].destinationAddress evidence(ipEvidence).ipAddress Os endereços IP passam para a evidência de IP.
confiança Sem substituição direta Use valores de veredicto em nível de evidência, como suspeito ou mal-intencionado, em vez de uma pontuação numérica.

Migrar seu aplicativo

Use estas etapas para migrar da API de alertas herdada para a nova API de alertas e incidentes.

Etapa 1: Identificar dependências

Antes de alterar qualquer código, identifique todas as integrações, scripts, conectores e processos downstream que atualmente chamam /security/alerts.

Etapa 2: conectar o Microsoft Sentinel para visibilidade unificada

Se você usa o Microsoft Sentinel, conecte seu espaço de trabalho ao portal do Microsoft Defender e confirme se as detecções relevantes são promovidas a incidentes. Sem essa integração, os alertas gerados pelo Sentinel não aparecem na API v2.

Enquanto você se prepara para a integração, use a API REST do Sentinel para recuperar alertas do Sentinel. Lembre-se de que não há suporte para alertas autônomos do Sentinel no novo modelo de API e a API REST do Sentinel será desativada no futuro. Priorize a integração do portal Defender antes do prazo de 15 de outubro de 2026.

Para obter mais informações, consulte Conectar o Microsoft Sentinel ao portal do Microsoft Defender e Transição do ambiente do Microsoft Sentinel para o portal do Defender.

Etapa 3: Atualizar pontos de extremidade e permissões da API

Para cada integração:

  1. Substitua chamadas por /security/alerts/security/alerts_v2 ou /security/incidents conforme apropriado para seu fluxo de trabalho.
  2. Atualize as permissões de registro do aplicativo e obtenha o consentimento do administrador.
  3. Documente todas as lacunas de autenticação e resolva-as antes do prazo de desativação.

Etapa 4: Atualizar o modelo de dados e a lógica de consulta

A migração v2 requer mais do que uma troca de campo por campo. Planeje as seguintes mudanças:

  • Trate incidentes como objetos de primeira classe: na v2, os alertas pertencem a incidentes. Considere criar seu fluxo de trabalho em torno de incidentes para obter a história completa do ataque.
  • Atualize a lógica de análise e enriquecimento: substitua as referências a userStates, hostStates, fileStatese networkConnections pelos objetos de evidência tipados correspondentes.
  • Reescrever filtros OData: atualize os filtros de consulta para usar os novos nomes de propriedade e a evidence/any() função para filtragem baseada em evidências.

Os exemplos a seguir mostram reescritas comuns de filtro.

Filtrar por produto ou origem

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

Filtrar por usuário envolvido

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

Filtrar por dispositivo envolvido

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

Consultas centradas em incidentes (nova funcionalidade)

# 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

Etapa 5: validar a cobertura e os fluxos de trabalho downstream

Antes de desativar sua integração herdada:

  1. Confirme se os alertas e incidentes esperados são retornados pela nova API.
  2. Verifique se os fluxos de trabalho downstream, como automação, relatórios e ingestão SIEM, funcionam corretamente após a migração.
  3. Analise as diferenças de cobertura conhecidas e identifique quaisquer fontes de dados complementares de que você ainda precisa.

Use uma ferramenta de teste de API como o Graph Explorer para validar suas consultas e inspecionar o novo modelo de dados.

Diferenças e limitações conhecidas

  • Cobertura do Microsoft Sentinel: os alertas gerados pelo Sentinel não são retornados pela API v2, a menos que seu espaço de trabalho do Sentinel esteja conectado ao portal do Microsoft Defender. Enquanto isso, use a API REST do Sentinel para recuperar esses alertas.
  • Alertas autônomos: os alertas que existem fora do modelo de incidente do Microsoft 365 Defender, incluindo detecções autônomas não promovidas a um incidente, não são retornados pela API v2.
  • Alertas ajustados: alertas suprimidos por regras de ajuste de alerta não são retornados por meio do alerts_v2 ponto de extremidade.
  • Eventos do Exchange Online de sinal baixo: determinados eventos do Exchange Online de sinal baixo, como criação de regra de caixa de correio e atrasos de mensagens, não estão incluídos no alerts_v2. Recupere-os por meio de logs de auditoria ou outras fontes de dados relevantes.

Conteúdo relacionado

  • Last updated on