Eseguire query KQL sul data lake di Microsoft Sentinel tramite API

Microsoft Sentinel data lake supporta l'esecuzione tramite codice di query in Kusto Query Language (KQL) usando API REST. L'utilizzo delle API REST consente ai team di sicurezza e ai sistemi di automazione di recuperare risultati analitici senza dover utilizzare il portale Azure o editor interattivi di query. Questo articolo illustra quando usare l'API, le autorizzazioni necessarie e come inviare una richiesta di query di base.

Quando usare l'API di query KQL

L'API di query KQL è progettata per scenari di accesso da sistema a sistema, tra cui:

  • Flussi di lavoro di automazione e orchestrazione
  • Servizi in background e attività pianificate
  • Agenti e strumenti di sicurezza che richiedono risultati di query come input
  • Integrazione con sistemi o agenti esterni

Per l'analisi interattiva e l'analisi ad hoc, eseguire invece query KQL dal portale di Defender.

Autenticazione e autorizzazioni

È possibile eseguire l'autenticazione all'API data lake Sentinel usando:

  • Un'entità servizio
  • Token di accesso utente

Nota

L'uso di un'entità servizio non è attualmente supportato per eseguire query sul data lake di Sentinel tramite l'API query KQL di Sentinel data lake per i ruoli Entra ID e i ruoli RBAC unificati di Microsoft Defender XDR.

Chiamata dell'API

Endpoint API

Tutte le query KQL vengono inviate usando l'endpoint REST seguente:

POST https://api.securityplatform.microsoft.com/lake/kql/v2/rest/query

Formato del corpo della richiesta

Una richiesta di query è costituita da:

  • La query KOL
  • Area di lavoro di destinazione, specificata come workspaceName-workspaceId

Parametri del payload

Campo Descrizione
csl Per eseguire la query KQL
DB Il nome dell'area di lavoro Sentinel e l'ID dell'area di lavoro

Payload di esempio:

{
"csl": "SigninLogs | take 10",
"db": "workspace1-12345678-abcd-abcd-1234-1234567890ab"
}

Invio della richiesta

La richiesta deve includere un token di connessione OAuth 2.0 nell'intestazione Authorization.

Authorization: Bearer <access_token>
Content-Type: application/json

L'API restituisce i risultati della query in un formato JSON strutturato che può essere elaborato da flussi di lavoro o applicazioni di automazione.

Impostazioni di interrogazione opzionali

È possibile includere opzioni di esecuzione aggiuntive nel payload della richiesta, ad esempio:

  • Timeout del server
  • Coerenza delle query
  • Applicazione di sola lettura

Timeout del server, coerenza delle query e opzioni di applicazione in sola lettura sono utili quando si esegue query in ambienti automatizzati o ad alta scala.

payload di esempio:

{
    "csl": "SigninLogs | take 10",
    "db": "workspace1-12345678-abcd-abcd-1234-1234567890ab",
    "properties": {
        "Options": {
            "servertimeout": "00:04:00",
            "queryconsistency": "strongconsistency",
            "query_language": "kql",
            "request_readonly": false,
            "request_readonly_hardline": false
        }
    }
}

Limiti e considerazioni sui servizi

L'esecuzione della query è soggetta a limiti di tempo e dimensioni dei risultati. Per i limiti attuali, vedere: limiti del servizio data lake di Microsoft Sentinel

Contenuto correlato

Per ulteriori informazioni, vedi le seguenti risorse:

  • Ultimo aggiornamento: