Avancerad jakt-API

  • Artikel

Gäller för:

Varning

Det här avancerade jakt-API:et är en äldre version med begränsade funktioner. En mer omfattande version av det avancerade jakt-API:et som kan köra frågor mot fler tabeller finns redan i Microsoft Graph-säkerhets-API:et. Se Avancerad jakt med Microsoft Graph-säkerhets-API

Vill du uppleva Microsoft Defender för Endpoint? Registrera dig för en kostnadsfri utvärderingsversion.

Obs!

Om du är en us government-kund använder du de URI:er som anges i Microsoft Defender för Endpoint för amerikanska myndighetskunder.

Tips

För bättre prestanda kan du använda servern närmare din geoplats:

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com
  • api-au.securitycenter.microsoft.com

Begränsningar

  1. Du kan bara köra en fråga på data från de senaste 30 dagarna.

  2. Resultatet innehåller högst 100 000 rader.

  3. Antalet körningar är begränsat per klientorganisation:

    • API-anrop: Upp till 45 anrop per minut och upp till 1 500 anrop per timme.
    • Körningstid: 10 minuters körningstid varje timme och 3 timmars körningstid per dag.

  4. Den maximala körningstiden för en enskild begäran är 200 sekunder.

  5. 429 svaret representerar att nå kvotgränsen, antingen efter antal begäranden eller efter CPU. Läs svarstexten för att förstå vilken gräns som har uppnåtts.

  6. Den maximala frågeresultatstorleken för en enskild begäran får inte överstiga 124 MB. Om den överskrids har en HTTP 400 Felaktig begäran med meddelandet "Frågekörningen har överskridit den tillåtna resultatstorleken. Optimera frågan genom att begränsa antalet resultat och försök igen" inträffar.

Behörigheter

En av följande behörigheter krävs för att anropa det här API:et. Mer information, inklusive hur du väljer behörigheter, finns i Använda Microsoft Defender för Endpoint-API:er

Behörighetstyp Behörighet Visningsnamn för behörighet
Program AdvancedQuery.Read.All Run advanced queries
Delegerat (arbets- eller skolkonto) AdvancedQuery.Read Run advanced queries

Obs!

När du hämtar en token med användarautentiseringsuppgifter:

  • Användaren måste ha rollen View Data tilldelad i Microsoft Entra ID
  • Användaren måste ha åtkomst till enheten baserat på enhetsgruppsinställningarna (mer information finns i Skapa och hantera enhetsgrupper)

Skapande av enhetsgrupp stöds i Defender för Endpoint Plan 1 och Plan 2.

HTTP-begäran

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

Frågerubriker

Rubrik Värde
Tillstånd Ägaren {token}. Krävs.
Content-Type application/json

Frågebrödtext

I begärandetexten anger du ett JSON-objekt med följande parametrar:

Parameter Typ Beskrivning
Fråga Text Frågan som ska köras. Krävs.

Svar

Om det lyckas returnerar den här metoden 200 OK och QueryResponse-objektet i svarstexten.

Exempel

Exempel på begäran

Här är ett exempel på begäran.

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

Svarsexempel

Här är ett exempel på svaret.

Obs!

Svarsobjektet som visas här kan trunkeras för korthet. Alla egenskaper returneras från ett faktiskt anrop.

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

Tips

Vill du veta mer? Engage med Microsofts säkerhetscommunity i vår Tech Community: Microsoft Defender för Endpoint Tech Community.