Uruchamianie zapytań KQL w Microsoft Sentinel data lake przy użyciu interfejsów API

Jezioro danych Microsoft Sentinel obsługuje programowe wykonywanie zapytań w języku zapytań Kusto (KQL) przy użyciu interfejsów API REST. Korzystanie z API REST umożliwia zespołom bezpieczeństwa i systemom automatyzacji pobieranie wyników analitycznych bez użycia portalu Azure czy interaktywnych edytorów zapytań. W tym artykule wyjaśniono, kiedy używać interfejsu API, wymaganych uprawnień i jak przesłać podstawowe żądanie zapytania.

Kiedy używać interfejsu API zapytań KQL

Interfejs API zapytań KQL jest przeznaczony do scenariuszy dostępu między systemami, w tym:

  • Przepływy pracy związane z automatyzacją i orkiestracją
  • Usługi w tle i zaplanowane zadania
  • Narzędzia agenta i narzędzia zabezpieczające, które wymagają wyników zapytań jako danych wejściowych
  • Integracja z zewnętrznymi systemami lub agentami

W przypadku interaktywnego dochodzenia i analizy ad hoc zamiast tego uruchamiaj zapytania KQL w portalu Defender.

Uwierzytelnianie i uprawnienia

Możesz uwierzytelnić się w interfejsie API usługi data lake Sentinel przy użyciu jednego z następujących elementów:

  • Jednostka usługi
  • Token dostępu użytkownika

Uwaga

Obecnie wykonywanie zapytań do jeziora danych Sentinel za pośrednictwem interfejsu API zapytań KQL jeziora danych Sentinel przy użyciu jednostki usługi oraz ról Entra ID i ujednoliconych ról RBAC usługi Microsoft Defender XDR nie jest obsługiwane.

Wywoływanie interfejsu API

Punkt końcowy interfejsu API

Wszystkie zapytania KQL są przesyłane przy użyciu następującego punktu końcowego REST:

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

Format treści żądania

Żądanie zapytania składa się z następujących elementów:

  • Zapytanie KQL
  • Docelowy obszar roboczy określony jako workspaceName-workspaceId

Parametry ładunku

Pole Opis
csl Zapytanie KQL do wykonania
db Nazwa obszaru roboczego Sentinel i identyfikator obszaru roboczego

Przykładowy ładunek:

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

Przesyłanie żądania

Żądanie musi zawierać token okaziciela OAuth 2.0 w nagłówku Authorization.

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

Interfejs API zwraca wyniki zapytania w ustrukturyzowanym formacie JSON, które mogą być przetwarzane przez zautomatyzowane przepływy pracy lub aplikacje.

Opcjonalne ustawienia zapytania

W ładunku żądania można uwzględnić dodatkowe opcje wykonywania, takie jak:

  • Przekroczenie limitu czasu serwera
  • Spójność zapytań
  • Wymuszenie trybu tylko do odczytu

Limity czasu serwera, spójność zapytań oraz opcje wymuszania tylko do odczytu są przydatne podczas uruchamiania zapytań w zautomatyzowanych lub skalowych środowiskach.

przykładowy ładunek danych:

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

Limity i uwagi dotyczące usługi

Wykonywanie zapytania podlega limitom czasu i rozmiaru wyniku. Aby uzyskać bieżące limity, zobacz: limity usługi Data Lake w Microsoft Sentinel

Zawartość pokrewna

Aby uzyskać więcej informacji, zobacz następujące zasoby:

  • Ostatnia aktualizacja o