Udostępnij przez

Interfejs API zaawansowanego wyszukiwania zagrożeń

  • Dotyczy: Microsoft Defender for Endpoint

Ostrzeżenie

Ten zaawansowany interfejs API wyszukiwania zagrożeń to starsza wersja z ograniczonymi możliwościami. Bardziej kompleksowa wersja zaawansowanego interfejsu API wyszukiwania zagrożeń, który może wykonywać zapytania dotyczące większej liczby tabel, jest już dostępna w interfejsie API zabezpieczeń programu Microsoft Graph. Zobacz Zaawansowane wyszukiwanie zagrożeń przy użyciu interfejsu API zabezpieczeń programu Microsoft Graph

Uwaga

Jeśli jesteś klientem rządowym USA, użyj identyfikatorów URI wymienionych w Ochrona punktu końcowego w usłudze Microsoft Defender dla klientów rządowych USA.

Porada

Aby uzyskać lepszą wydajność, zamiast korzystać z api.security.microsoft.com, użyj serwera bliżej lokalizacji geograficznej:

  • 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

Ograniczenia

  • Zapytanie można uruchamiać tylko na danych z ostatnich 30 dni.

  • Wyniki obejmują maksymalnie 100 000 wierszy.

  • Liczba wykonań jest ograniczona na dzierżawę:

    • Wywołania interfejsu API: do 45 wywołań na minutę i do 1500 wywołań na godzinę.
    • Czas wykonywania: 10 minut czasu trwania co godzinę i 3 godziny czasu trwania dziennie.

  • Maksymalny czas wykonywania pojedynczego żądania wynosi 200 sekund.

  • 429 odpowiedź oznacza osiągnięcie limitu przydziału według liczby żądań lub procesora CPU. Przeczytaj treść odpowiedzi, aby zrozumieć, jaki limit został osiągnięty.

  • Maksymalny rozmiar wyniku zapytania pojedynczego żądania nie może przekraczać 124 MB. Jeśli zostanie przekroczona, żądanie HTTP 400 Nieprawidłowe z komunikatem "Wykonanie zapytania przekroczyło dozwolony rozmiar wyniku. Zoptymalizuj zapytanie, ograniczając liczbę wyników i ponów próbę".

Uprawnienia

Do wywołania tego interfejsu API jest wymagane jedno z następujących uprawnień. Aby dowiedzieć się więcej, w tym jak wybrać uprawnienia, zobacz Korzystanie z interfejsów API Ochrona punktu końcowego w usłudze Microsoft Defender

Typ uprawnień Uprawnienie Nazwa wyświetlana uprawnień
Aplikacja AdvancedQuery.Read.All Run advanced queries
Delegowane (konto służbowe) AdvancedQuery.Read Run advanced queries

Uwaga

Podczas uzyskiwania tokenu przy użyciu poświadczeń użytkownika:

  • Użytkownik musi mieć przypisaną View Data rolę w Tożsamość Microsoft Entra.

  • Użytkownik musi mieć dostęp do urządzenia na podstawie ustawień grupy urządzeń (zobacz Tworzenie grup urządzeń i zarządzanie nimi , aby uzyskać więcej informacji).

    Tworzenie grupy urządzeń jest obsługiwane w usłudze Defender for Endpoint Plan 1 i Plan 2.

Żądanie HTTP

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

Nagłówki żądań

Nagłówek Value
Autoryzacji Element nośny {token}. Wymagane.
Typ zawartości application/json

Treść żądania

W treści żądania podaj obiekt JSON z następującymi parametrami:

Parametr Wpisać Opis
Kwerendy Tekst Zapytanie do uruchomienia. Wymagane.

Odpowiedzi

Jeśli to się powiedzie, ta metoda zwraca wartość 200 OK i obiekt QueryResponse w treści odpowiedzi.

Przykład

Przykład żądania

Oto przykład żądania.

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

Przykład odpowiedzi

Oto przykład odpowiedzi.

Uwaga

Pokazany tutaj obiekt odpowiedzi może zostać obcięty z powodu zwięzłości. Wszystkie właściwości zostaną zwrócone z rzeczywistego wywołania.

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

Porada

Chcesz dowiedzieć się więcej? Zaangażuj się w społeczność rozwiązań zabezpieczających firmy Microsoft w naszej społeczności technicznej Społeczność techniczna usługi Ochrona punktu końcowego w usłudze Microsoft Defender.

  • Last updated on