Ausführen von KQL-Abfragen für den Microsoft Sentinel Data Lake mithilfe von APIs

Microsoft Sentinel Data Lake unterstützt die programmgesteuerte Ausführung von Abfragen in der Kusto-Abfragesprache (KQL) mithilfe von REST-APIs. Die Nutzung der REST-APIs ermöglicht es Sicherheitsteams und Automatisierungssystemen, analytische Ergebnisse abzurufen, ohne das Azure-Portal oder interaktive Abfrageeditoren zu verwenden. In diesem Artikel wird erläutert, wann die API verwendet werden sollte, welche Berechtigungen erforderlich sind, und wie Sie eine grundlegende Abfrageanforderung übermitteln.

Wann die KQL-Abfrage-API verwendet werden sollte

Die KQL-Abfrage-API ist für System-zu-System-Zugriffsszenarien konzipiert, einschließlich:

  • Automatisierungs- und Orchestrierungsworkflows
  • Hintergrunddienste und geplante Aufträge
  • Agent- und Sicherheitstools, die Abfrageergebnisse als Eingabe erfordern
  • Integration mit externen Systemen oder Agenten

Führen Sie für interaktive Untersuchungen und Ad-hoc-Analysen stattdessen KQL-Abfragen über das Defender-Portal aus.

Authentifizierung und Berechtigungen

Sie können sich bei der Sentinel Data Lake-API authentifizieren, indem Sie eine der folgenden Methoden verwenden:

  • Ein Service Principal
  • Ein Benutzerzugriffstoken

Hinweis

Bei Verwendung eines Dienstprinzipals werden derzeit Entra ID-Rollen und einheitliche RBAC-Rollen von Microsoft Defender XDR für die Abfrage des Sentinel Data Lakes über die Sentinel Data Lake-KQL-Abfrage-API nicht unterstützt.

Aufrufen der API

API-Endpunkt

Alle KQL-Abfragen werden mit dem folgenden REST-Endpunkt übermittelt:

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

Format des Anforderungstexts

Eine Abfrageanforderung besteht aus:

  • Die KQL-Abfrage
  • Der Zielarbeitsbereich, angegeben als workspaceName-workspaceId

Nutzlastparameter

Feld Beschreibung
csl Die auszuführende KQL-Abfrage
db Der Name des Sentinel-Arbeitsbereichs und die ID des Arbeitsbereichs

Beispielnutzlast:

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

Übermitteln der Anforderung

Die Anforderung muss ein OAuth 2.0-Bearertoken im Autorisierungsheader enthalten.

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

Die API gibt Abfrageergebnisse in einem strukturierten JSON-Format zurück, das von Automatisierungsworkflows oder Anwendungen verarbeitet werden kann.

Optionale Abfrageeinstellungen

Sie können zusätzliche Ausführungsoptionen in die Anforderungsnutzlast einschließen, z. B.:

  • Server Timeout
  • Abfragekonsistenz
  • Nur-Lese-Durchsetzung

Server-Timeout, Abfragekonsistenz und Read-Only-Durchsetzung sind nützlich, wenn Abfragen in automatisierten oder großflächigen Umgebungen durchgeführt werden.

Beispielnutzlast:

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

Dienstgrenzwerte und Überlegungen

Die Abfrageausführung unterliegt Zeit- und Ergebnisgrößenbeschränkungen. Aktuelle Grenzwerte finden Sie unter Microsoft Sentinel Data Lake-Dienstgrenzwerte.

Verwandte Inhalte

Weitere Informationen finden Sie in den folgenden Ressourcen:

  • Zuletzt aktualisiert um