API di rilevazione avanzata

  • Articolo

Si applica a:

Avviso

Questa API di ricerca avanzata è una versione precedente con 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. Vedere Ricerca avanzata con l'API di sicurezza di Microsoft Graph

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

Limitazioni

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

  2. I risultati includono un massimo di 100.000 righe.

  3. 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.

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

  5. 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.

  6. Le dimensioni massime del risultato della query di una singola richiesta non possono superare i 124 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, incluso come scegliere le autorizzazioni, vedere Usare le API di 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 (vedere Creare e gestire gruppi di dispositivi per altre informazioni)

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

Richiesta HTTP

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

Intestazioni della richiesta

Intestazione Valore
Autorizzazione Bearer {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.securitycenter.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ù, Collaborare con la community di Microsoft Security nella community tech: Microsoft Defender per endpoint Tech Community.