Rozhraní API rozšířeného proaktivního vyhledávání

  • Článek

Platí pro:

Upozornění

Toto rozhraní API pro pokročilé proaktivního vyhledávání je starší verze s omezenými možnostmi. V rozhraní Microsoft Graph Security API je již k dispozici komplexnější verze rozhraní API pro pokročilé proaktivního vyhledávání, které dokáže dotazovat více tabulek. Viz Rozšířené proaktivní vyhledávání s využitím rozhraní Microsoft Graph Security API.

Chcete vyzkoušet Defender pro Endpoint? Zaregistrujte se a získejte bezplatnou zkušební verzi,

Poznámka

Pokud jste zákazníkem státní správy USA, použijte identifikátory URI uvedené v Microsoft Defender for Endpoint pro zákazníky státní správy USA.

Tip

Pro lepší výkon můžete použít server blíže k vašemu geografickému umístění:

  • 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

Omezení

  1. Dotaz můžete spustit jenom na data za posledních 30 dnů.

  2. Výsledky obsahují maximálně 100 000 řádků.

  3. Počet spuštění je omezený na tenanta:

    • Volání rozhraní API: Až 45 volání za minutu a až 1 500 volání za hodinu.
    • Doba provádění: 10 minut doby spuštění každou hodinu a 3 hodiny běhu denně.

  4. Maximální doba provádění jednoho požadavku je 200 sekund.

  5. 429 odpověď představuje dosažení limitu kvóty podle počtu požadavků nebo procesoru. Přečtěte si text odpovědi, abyste pochopili, jakého limitu bylo dosaženo.

  6. Maximální velikost výsledku dotazu jednoho požadavku nesmí překročit 124 MB. Při překročení se zobrazí chybný požadavek HTTP 400 se zprávou "Provádění dotazu překročilo povolenou velikost výsledku. Optimalizujte dotaz omezením počtu výsledků a zkuste to znovu."

Oprávnění

K volání tohoto rozhraní API se vyžaduje jedno z následujících oprávnění. Další informace, včetně postupu výběru oprávnění, najdete v tématu Použití rozhraní MICROSOFT DEFENDER FOR ENDPOINT API.

Typ oprávnění Oprávnění Zobrazovaný název oprávnění
Application AdvancedQuery.Read.All Run advanced queries
Delegovaný (pracovní nebo školní účet) AdvancedQuery.Read Run advanced queries

Poznámka

Při získávání tokenu pomocí přihlašovacích údajů uživatele:

  • Uživatel musí mít přiřazenou View Data roli v Microsoft Entra ID
  • Uživatel musí mít přístup k zařízení na základě nastavení skupiny zařízení (další informace najdete v tématu Create a správa skupin zařízení).

Vytváření skupin zařízení je podporováno v defenderu for Endpoint Plan 1 a Plan 2.

Požadavek HTTP

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

Hlavičky požadavků

Záhlaví Hodnota
Autorizace Nosný {token}. Povinné.
Typ obsahu application/json

Text požadavku

V textu požadavku zadejte objekt JSON s následujícími parametry:

Parametr Typ Popis
Dotazu Text Dotaz, který se má spustit. Povinné.

Reakce

V případě úspěchu vrátí tato metoda 200 OK a QueryResponse objekt v těle odpovědi.

Příklad

Příklad požadavku

Tady je příklad požadavku.

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

Příklad odpovědi

Tady je příklad odpovědi.

Poznámka

Zde zobrazený objekt odpovědi může být kvůli stručnosti zkrácen. Všechny vlastnosti se vrátí ze skutečného volání.

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

Tip

Chcete se dozvědět více? Engage s komunitou Microsoft Security v naší technické komunitě: Microsoft Defender for Endpoint Tech Community.