Udostępnij za pośrednictwem

Interfejs API zaawansowanego wyszukiwania zagrożeń

  • Artykuł

Dotyczy:

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

Chcesz poznać usługę ochrony punktu końcowego w usłudze Microsoft Defender? Utwórz konto, aby skorzystać z bezpłatnej wersji próbnej.

Uwaga

Jeśli jesteś klientem rządowym USA, użyj identyfikatorów URI wymienionych w usłudze Microsoft Defender for Endpoint dla klientów rządowych USA.

Porada

Aby uzyskać lepszą wydajność, możesz użyć 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

Ograniczenia

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

  2. Wyniki obejmują maksymalnie 100 000 wierszy.

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

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

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

  6. 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 usługi Microsoft Defender dla interfejsów API punktu końcowego

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 identyfikatorze 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.securitycenter.microsoft.com/api/advancedqueries/run

Nagłówki żądań

Nagłówek Value
Autoryzacja 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
Zapytanie Tekst Zapytanie do uruchomienia. Wymagane.

Odpowiedź

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.securitycenter.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? Skontaktuj się ze społecznością zabezpieczeń firmy Microsoft w naszej społeczności technicznej: Microsoft Defender for Endpoint Tech Community.