Migrar de alertas legados para a API de alertas e incidentes

A API legada de alertas de segurança do Microsoft Graph disponível através do /security/alerts ponto final foi preterida e será descontinuada a 31 de agosto de 2026. Se a aplicação utilizar atualmente a API de alertas legados para obter, monitorizar ou gerir alertas de segurança, deve migrar para a nova API de alertas e incidentes no Microsoft 365 Defender, disponível através do /security/alerts_v2 ponto final.

Este artigo descreve as principais diferenças entre as duas APIs, fornece uma referência de mapeamento de campos e descreve os passos para migrar a sua aplicação.

Importante

  • Após 31 de agosto de 2026, o ponto final legado /security/alerts deixará de devolver dados. Migre as aplicações antes deste prazo para evitar interrupções nos fluxos de trabalho das operações de segurança.

  • A API de novos alertas e incidentes não é uma substituição direta, um-para-um para a API de alertas legados. Apresenta alertas que fazem parte do ecossistema do Microsoft 365 Defender. Os alertas de origens que não estão integrados no Microsoft 365 Defender, como uma área de trabalho Microsoft Sentinel que não está ligada ao portal Microsoft Defender ou alertas autónomos e otimizados, não são devolvidos pela nova API. Reveja a secção de diferenças e limitações conhecidas antes de iniciar a 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 a jusante que chamam /security/alerts.
  • Se utilizar Microsoft Sentinel, verifique se a área de trabalho está ligada ao portal do Microsoft Defender. Sentinel alertas gerados não estão disponíveis através da API v2 até concluir essa integração. Entretanto, utilize a API REST Sentinel para obter alertas de Sentinel. Os alertas de Sentinel autónomos não são suportados na API v2 e a API REST Sentinel será descontinuada no futuro.
  • Reveja as diferenças e limitações conhecidas para identificar quaisquer origens de dados suplementares que os fluxos de trabalho possam exigir.

Porquê migrar?

A API de novos alertas e incidentes oferece melhorias significativas na API de alertas legados:

  • Correlação automática: os alertas de vários sinais ( identidade, ponto final, e-mail e cloud) são automaticamente agrupados em incidentes, dando aos analistas uma visão mais ampla de um ataque.
  • Provas mais ricas: as coleções de estados legados (userStates, hostStates, fileStates) são substituídas por mais de 40 objetos de evidências fortemente escritos, como userEvidence, azureResourceEvidence, aiAgentEvidencee analyzedMessageEvidence que são mais fáceis de trabalhar através de programação.
  • Modelo centrado em incidentes: a nova API introduz um objeto de incidente de primeira classe que representa a história de ataque completa, permitindo uma investigação e resposta mais eficazes.
  • Cobertura de ameaças expandida: a API unificada inclui origens adicionais, como Prevenção Contra Perda de Dados do Microsoft Purview e Gestão de Riscos Internos.
  • Contexto de ameaça mais avançado: os alertas e os incidentes incluem técnicas MITRE ATT&CK, origens de deteção e classificação de ameaças.

Diferenças da API

Pontos de extremidade

A tabela seguinte lista as alterações do ponto final.

Operação Ponto final legado Novo ponto final
Listar alertas GET /v1.0/security/alerts GET /v1.0/security/alerts_v2
Obter 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 registo de aplicações tem de ser atualizado com novos âmbitos de permissão do Microsoft Graph.

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

Depois de adicionar as novas permissões ao registo de aplicações, um administrador tem de conceder consentimento antes de a aplicação poder utilizá-las na produção.

Para obter mais informações sobre estas permissões, consulte Referência de permissões do Microsoft Graph.

Mapeamento de campos

A tabela seguinte mapeia os campos de alertas v1 legados para os respetivos alertas v2 equivalentes. Este mapeamento abrange apenas os campos que existem na v1 e têm um equivalente direto ou aproximado na v2. A nova API inclui muitos campos adicionais que fornecem contexto mais avançado sobre alertas e incidentes.

campo v1 Campo v2 Observações
azureTenantId tenantId O mesmo significado, propriedade cujo nome foi mudado.
lastModifiedDateTime lastUpdateDateTime Controla a hora da atualização mais recente.
closedDateTime resolvedDateTime Representa quando o alerta foi resolvido.
activityGroupName actorDisplayName Campo mudado para o contexto de ator.
comentários classificação + determinação V2 separa a eliminação da determinação do tipo de ataque.
vendorInformation.provider serviceSource + productName Os metadados do fornecedor são divididos numa enumeração e num nome a apresentar.
sourceMaterials[] alertWebUrl + incidentWebUrl As ligações do portal apontam agora para a experiência unificada do Defender.
eventDateTime firstActivityDateTime + lastActivityDateTime O carimbo de data/hora único torna-se um intervalo de tempo.
incidentIds[] incidentId Cada alerta pertence agora a exatamente um incidente.
userStates[].userPrincipalName evidence(userEvidence).userAccount.userPrincipalName As entidades de utilizador movem-se para objetos de provas digitados.
hostStates[].fqdn evidence(deviceEvidence).deviceDnsName As informações do anfitrião são movidas para as provas do dispositivo.
fileStates[].name / fileHash.hashValue evidence(fileEvidence).fileName / fileDetails.sha256 Os metadados de ficheiros e os hashes são movidos para provas de ficheiros.
networkConnections[].destinationUrl evidence(urlEvidence).url Os artefactos de rede decompõem-se em tipos de provas separados.
networkConnections[].destinationAddress evidence(ipEvidence).ipAddress Os endereços IP são movidos para provas de IP.
confiança Sem substituição direta Utilize valores de veredicto ao nível da evidência, como suspeito ou malicioso, em vez de uma pontuação numérica.

Migrar a sua aplicação

Utilize estes passos para migrar da API de alertas legados para a nova API de alertas e incidentes.

Passo 1: Identificar dependências

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

Passo 2: Ligar Microsoft Sentinel para visibilidade unificada

Se utilizar Microsoft Sentinel, ligue a área de trabalho ao portal Microsoft Defender e confirme que as deteções relevantes são promovidas em incidentes. Sem esta integração, os alertas gerados Sentinel não aparecem na API v2.

Enquanto se prepara para a integração, utilize a API REST Sentinel para obter Sentinel alertas. Tenha em atenção que os alertas de Sentinel autónomos não são suportados no novo modelo de API e que a API REST Sentinel será descontinuada no futuro. Priorize a inclusão do portal do Defender antes do prazo de 31 de agosto de 2026.

Para obter mais informações, veja Connect Microsoft Sentinel to the Microsoft Defender portal and Transition your Microsoft Sentinel environment to the Defender portal (Ligar Microsoft Sentinel ao portal do Microsoft Defender e Fazer a transição do ambiente de Microsoft Sentinel para o portal do Defender).

Passo 3: Atualizar os pontos finais e as permissões da API

Para cada integração:

  1. Substitua as chamadas para /security/alerts por /security/alerts_v2 ou /security/incidents conforme adequado para o fluxo de trabalho.
  2. Atualize as permissões de registo de aplicações e obtenha o consentimento do administrador.
  3. Documente eventuais lacunas de autenticação e resolve-las antes do prazo de extinção.

Passo 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. Planeie as seguintes alterações:

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

Os exemplos seguintes mostram reescritas de filtros comuns.

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 utilizador 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 capacidade)

# 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

Passo 5: Validar a cobertura e os fluxos de trabalho a jusante

Antes de extinguir a integração legada:

  1. Confirme que os alertas e incidentes esperados são devolvidos pela nova API.
  2. Verifique se os fluxos de trabalho a jusante, como automatização, relatórios e ingestão de SIEM, funcionam corretamente após a migração.
  3. Reveja as diferenças de cobertura conhecidas e identifique as origens de dados suplementares de que ainda precisa.

Utilize uma ferramenta de teste de API, como o Graph Explorer, para validar as consultas e inspecionar o novo modelo de dados.

Diferenças e limitações conhecidas

  • Microsoft Sentinel cobertura: os alertas gerados Sentinel não são devolvidos pela API v2, a menos que a área de trabalho Sentinel esteja ligada ao portal do Microsoft Defender. Entretanto, utilize a API REST Sentinel para obter estes alertas.
  • Alertas autónomos: os alertas que existem fora do modelo de incidentes do Microsoft 365 Defender ( incluindo deteções autónomas não promovidas para um incidente) não são devolvidos pela API v2.
  • Alertas otimizados: os alertas suprimidos pelas regras de otimização de alertas não são devolvidos através do alerts_v2 ponto final.
  • Eventos de Exchange Online de sinal baixo: determinados eventos de Exchange Online de sinal baixo, como a criação de regras de caixa de correio e atrasos de mensagens, não estão incluídos no alerts_v2. Obtenha-os através de registos de auditoria ou de outras origens de dados relevantes.

Conteúdo relacionado

  • Last updated on