API di rilevazione avanzata

  • Si applica a: Microsoft Defender for Endpoint

Avviso

L'API di ricerca avanzata Microsoft Defender per endpoint è obsoleta e include funzionalità limitate. Una versione più completa dell'API di ricerca avanzata in grado di eseguire query su più tabelle è già disponibile nell'API di sicurezza di Microsoft Graph. Per altre informazioni, vedere Ricerca avanzata con Microsoft Graph API di sicurezza.

L'API di ricerca avanzata Microsoft Defender per endpoint sta passando all'API di sicurezza Microsoft Graph, che include funzionalità di ricerca avanzate. L'API di sicurezza Microsoft Graph offre una copertura dei dati più ampia, una coerenza migliorata e una migliore scalabilità per i flussi di lavoro di automazione e sicurezza. Il ritiro è iniziato nel gennaio 2026. Al termine del ritiro, l'API di ricerca avanzata Microsoft Defender per endpoint non funziona più. Per la sequenza temporale del ritiro, vedere MC1220762. Per altre informazioni sulla migrazione, vedere Usare l'API di sicurezza Microsoft Graph.

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, anziché usare api.security.microsoft.com, usare un server più vicino alla georilevazione:

  • 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
  • aea.api.security.microsoft.com

Limitazioni

  • È possibile eseguire una query solo sui dati degli ultimi 30 giorni.

  • I risultati includono un massimo di 100.000 righe.

  • Il numero di esecuzioni è limitato per ogni tenant:

    • Chiamate API: fino a 45 chiamate al minuto e fino a 1.500 chiamate all'ora.
    • Tempo di esecuzione: 10 minuti di tempo di esecuzione ogni ora e 3 ore di esecuzione al giorno.

  • Il tempo massimo di esecuzione di una singola richiesta è di 200 secondi.

  • 429 response rappresenta il raggiungimento del limite di quota in base al numero di richieste o alla CPU. Leggere il corpo della risposta per comprendere quale limite è stato raggiunto.

  • Le dimensioni massime dei risultati della query di una singola richiesta non possono superare i 50 MB. Se superato, una richiesta HTTP 400 non valida con il messaggio "Esecuzione query ha superato le dimensioni consentite del risultato. Ottimizzare la query limitando il numero di risultati e riprovare".

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 AdvancedQuery.Read.All Run advanced queries
Delegato (account aziendale o dell'istituto di istruzione) AdvancedQuery.Read Run advanced queries

Nota

Quando si ottiene un token usando le credenziali utente:

  • L'utente deve avere il View Data ruolo assegnato in Microsoft Entra ID.

  • L'utente deve avere accesso al dispositivo in base alle impostazioni del gruppo di dispositivi .Per altre informazioni, vedere Creare e gestire gruppi di dispositivi .

    La creazione di gruppi di dispositivi è supportata in Defender per endpoint Piano 1 e Piano 2.

Richiesta HTTP

POST https://api.security.microsoft.com/api/advancedqueries/run

Intestazioni della richiesta

Intestazione Valore
Autorizzazione Connessione {token}. Obbligatorio.
Content-Type application/json

Corpo della richiesta

Nel corpo della richiesta specificare un oggetto JSON con i parametri seguenti:

Parametro Tipo Descrizione
Query Testo Query da eseguire. Obbligatorio.

Risposta

In caso di esito positivo, questo metodo restituisce 200 OK e l'oggetto QueryResponse nel corpo della risposta.

Esempio

Esempio di richiesta

Ecco un esempio della richiesta.

POST https://api.security.microsoft.com/api/advancedqueries/run

{"Query":"DeviceProcessEvents |where InitiatingProcessFileName =~ 'powershell.exe' |where ProcessCommandLine contains 'appdata'|project Timestamp, FileName, InitiatingProcessFileName, DeviceId|limit 2"}

Esempio di risposta

Ecco un esempio della risposta.

Nota

L'oggetto risposta illustrato qui può essere troncato per brevità. Tutte le proprietà verranno restituite da una chiamata effettiva.

{
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "DeviceId",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-02-05T01:10:26.2648757Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        },
        {
            "Timestamp": "2020-02-05T01:10:26.5614772Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        }
    ]
}

Consiglio

Per saperne di più, Interagisci con la community Microsoft Security nella Community Tech: Community Tech di Microsoft Defender per endpoint.

  • Last updated on