Criar API de alerta

Artigo
02/20/2025

Aplica-se a:

Deseja experimentar o Microsoft Defender para Ponto de Extremidade? Inscreva-se para uma avaliação gratuita.

Observação

Se for um cliente do Governo norte-americano, utilize os URIs listados no Microsoft Defender para Ponto de Extremidade para clientes do Us Government.

Dica

Para um melhor desempenho, pode utilizar o servidor mais próximo da localização geográfica:

us.api.security.microsoft.com
eu.api.security.microsoft.com
uk.api.security.microsoft.com
au.api.security.microsoft.com
swa.api.security.microsoft.com
ina.api.security.microsoft.com

Descrição da API

Cria um novo Alerta sobre o Evento.

Microsoft Defender para Ponto de Extremidade Evento é necessário para a criação do alerta.
Tem de fornecer três parâmetros do Evento no pedido: Hora do Evento, ID do Computador e ID do Relatório. Veja o exemplo a seguir.
Pode utilizar um evento encontrado na API de Investigação Avançada ou no Portal.
Se existir um alerta aberto no mesmo Dispositivo com o mesmo Título, o novo alerta criado é intercalado com o mesmo.
Uma investigação automática é iniciada automaticamente em alertas criados através da API.

Limitações

As limitações de taxa para esta API são de 15 chamadas por minuto.

Permissões

Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, veja Utilizar Microsoft Defender para Ponto de Extremidade APIs.

Tipo de permissão	Permissão	Nome a apresentar da permissão
Application	Alert.ReadWrite.All	"Ler e escrever todos os alertas"
Delegado (conta corporativa ou de estudante)	Alert.ReadWrite	"Alertas de leitura e escrita"

Observação

Ao obter um token com credenciais de utilizador:

O utilizador tem de ter, pelo menos, a seguinte permissão de função: Investigação de alertas. Para obter mais informações, veja Criar e gerir funções.
O utilizador tem de ter acesso ao dispositivo associado ao alerta, com base nas definições do grupo de dispositivos. Para obter mais informações, veja Criar e gerir grupos de dispositivos.

A criação do Grupo de Dispositivos é suportada no Plano 1 e Plano 2 do Defender para Endpoint

Solicitação HTTP

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

Cabeçalhos de solicitação

Nome	Tipo	Descrição
Autorização	Cadeia de caracteres	{token} de portador. Obrigatório.
Content-Type	Cadeia de Caracteres	application/json. Obrigatório.

Corpo da solicitação

No corpo do pedido, forneça os seguintes valores (todos são necessários):

Propriedade	Tipo	Descrição
eventTime	DateTime(UTC)	O tempo exata do evento como cadeia, conforme obtido a partir da investigação avançada. Por exemplo, `2018-08-03T16:45:21.7115183Z`Obrigatório.
reportId	Cadeia de caracteres	O reportId do evento, conforme obtido da investigação avançada. Obrigatório.
machineId	Cadeia de caracteres	ID do dispositivo no qual o evento foi identificado. Obrigatório.
severity	Cadeia de caracteres	Gravidade do alerta. Os valores das propriedades são: "Baixo", "Médio" e "Alto". Obrigatório.
title	Cadeia de caracteres	Título do alerta. Obrigatório.
description	Cadeia de caracteres	Descrição do alerta. Obrigatório.
recommendedAction	Cadeia de caracteres	O agente de segurança tem de efetuar esta ação ao analisar o alerta. Obrigatório.
category	Cadeia de caracteres	Categoria do alerta. Os valores das propriedades são: "Geral", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "LateralMovement", "Malware", "Persistence", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" Necessário.

Resposta

Se for bem-sucedido, este método devolve 200 OK e um novo objeto de alerta no corpo da resposta. Se o evento com as propriedades especificadas (reportId, eventTime e machineId) não tiver sido encontrado – 404 Não Encontrado.

Exemplo

Solicitação

Eis um exemplo do pedido.

POST https://api.securitycenter.microsoft.com/api/alerts/CreateAlertByReference

{
    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
    "severity": "Low",
    "title": "example",
    "description": "example alert",
    "recommendedAction": "nothing",
    "eventTime": "2018-08-03T16:45:21.7115183Z",
    "reportId": "20776",
    "category": "Exploit"
}