Api för avancerad sökning

Gäller för: Microsoft Defender för slutpunkt

Anteckning

Om du är myndighetskund i USA kan du använda de URI:er som visas i Microsoft Defender för Slutpunkt för kunder inom myndigheter i USA.

Tips

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

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

Begränsningar

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

  2. Resultatet kommer att innehålla högst 100 000 rader.

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

    • API-samtal: Upp till 45 samtal per minut, upp till 1 500 samtal 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 10 minuter.

  5. 429-svar motsvarar en kvotgräns, antingen genom antal begäranden eller av cpu:n. Läs svarstext för att förstå vilken gräns som har nåtts.

  6. Den maximala frågeresultatstorleken för en enskild begäran får inte överstiga 124 MB. Om den överskrids: HTTP 400 Bad Request 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" visas.

Behörigheter

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

Behörighetstyp Behörighet Visningsnamn för behörighet
Program AdvancedQuery.Read.All Kör avancerade frågor
Delegerat (arbets- eller skolkonto) AdvancedQuery.Read Kör avancerade frågor

Anteckning

När du skaffar en token med hjälp av användarautentiseringsuppgifter:

  • Användaren måste ha AD-rollen "Visa data"
  • Användaren måste ha åtkomst till enheten baserat på enhetsgruppinställningar (mer information finns i Skapa och hantera enhetsgrupper)

HTTP-begäran

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

Frågerubriker

Rubrik Värde
Auktorisering Bearer {token}. Obligatoriskt.
Content-Type application/json

Frågebrödtext

Ange följande parametrar för ett JSON-objekt i begärans brödtext:

Parameter Typ Beskrivning
Fråga Text Frågan som ska köras. Obligatoriskt.

Svar

Om det lyckas returnerar den här metoden 200 OK och objektet QueryResponse i svarets brödtext.

Exempel

Exempel på förfrågan

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.

Anteckning

Det svarsobjekt som visas här kan trunkeras för korthet. Alla egenskaper returneras från ett faktiskt samtal.

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