Creare un'API di avviso

Articolo
02/20/2025

Si applica a:

Se si desidera provare Microsoft Defender per endpoint, iscriversi a una versione di valutazione gratuita.

Nota

Se si è un cliente del governo degli Stati Uniti, usare gli URI elencati in Microsoft Defender per endpoint per i clienti del governo degli Stati Uniti.

Consiglio

Per ottenere prestazioni migliori, è possibile usare il server più vicino alla posizione geografica:

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

Descrizione DELL'API

Crea un nuovo avviso in cima all'evento.

Microsoft Defender per endpoint Evento è necessario per la creazione dell'avviso.
È necessario specificare tre parametri dall'evento nella richiesta: Ora evento, ID computer e ID report. Vedere l'esempio che segue.
È possibile usare un evento disponibile nell'API di ricerca avanzata o nel portale.
Se esiste un avviso aperto nello stesso dispositivo con lo stesso titolo, il nuovo avviso creato viene unito con esso.
Un'analisi automatica viene avviata automaticamente sugli avvisi creati tramite l'API.

Limitazioni

Le limitazioni di frequenza per questa API sono di 15 chiamate al minuto.

Autorizzazioni

Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, inclusa la scelta delle autorizzazioni, vedere Usare le API Microsoft Defender per endpoint.

Tipo di autorizzazione	Autorizzazione	Nome visualizzato autorizzazioni
Applicazione	Alert.ReadWrite.All	'Leggere e scrivere tutti gli avvisi'
Delegato (account aziendale o dell'istituto di istruzione)	Alert.ReadWrite	'Avvisi di lettura e scrittura'

Nota

Quando si ottiene un token usando le credenziali utente:

L'utente deve disporre almeno dell'autorizzazione del ruolo seguente: Analisi degli avvisi. Per altre informazioni, vedere Creare e gestire ruoli.
L'utente deve avere accesso al dispositivo associato all'avviso, in base alle impostazioni del gruppo di dispositivi. Per altre informazioni, vedere Creare e gestire gruppi di dispositivi.

La creazione del gruppo di dispositivi è supportata sia in Defender per endpoint piano 1 che in piano 2

Richiesta HTTP

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

Intestazioni di richiesta

Nome	Tipo	Descrizione
Autorizzazione	Stringa	Bearer {token}. Obbligatorio.
Content-Type	Stringa	application/json. Obbligatorio.

Corpo della richiesta

Nel corpo della richiesta specificare i valori seguenti (tutti sono obbligatori):

Proprietà	Tipo	Descrizione
eventTime	DateTime(UTC)	Tempo preciso dell'evento come stringa, ottenuto dalla ricerca avanzata. Ad esempio, `2018-08-03T16:45:21.7115183Z`Obbligatorio.
reportId	Stringa	ReportId dell'evento, ottenuto dalla ricerca avanzata. Obbligatorio.
machineId	Stringa	ID del dispositivo in cui è stato identificato l'evento. Obbligatorio.
severità	Stringa	Gravità dell'avviso. I valori delle proprietà sono: 'Low', 'Medium' e 'High'. Obbligatorio.
title	Stringa	Titolo per l'avviso. Obbligatorio.
descrizione	Stringa	Descrizione dell'avviso. Obbligatorio.
recommendedAction	Stringa	Il responsabile della sicurezza deve eseguire questa azione durante l'analisi dell'avviso. Obbligatorio.
categoria	Stringa	Categoria dell'avviso. I valori della proprietà sono: "General", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "LateralMovement", "Malware", "Persistence", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" Required.

Risposta

In caso di esito positivo, questo metodo restituisce 200 OK e un nuovo oggetto avviso nel corpo della risposta. Se l'evento con le proprietà specificate (reportId, eventTime e machineId) non è stato trovato- 404 Non trovato.

Esempio

Richiesta

Ecco un esempio della richiesta.

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"
}