Share via

Tarkennetun etsinnän ohjelmointirajapinta

  • Artikkeli

Koskee seuraavia:

Varoitus

Tämä kehittynyt metsästyksen ohjelmointirajapinta on vanhempi versio, jolla on rajoitetut ominaisuudet. Kattavampi versio kehittyneestä metsästyksen ohjelmointirajapinnasta, joka voi kysellä useampia taulukoita, on jo käytettävissä Microsoft Graph security -ohjelmointirajapinnassa. Katso Kehittynyt metsästys Microsoft Graph security -ohjelmointirajapinnan avulla

Haluatko kokea Microsoft Defender for Endpointin? Rekisteröidy maksuttomaan kokeiluversioon.

Huomautus

Jos olet Yhdysvaltain valtionhallinnon asiakas, käytä Microsoft Defender for Endpoint lueteltuja URI-tunnuksia Yhdysvaltain valtionhallinnon asiakkaille.

Vihje

Suorituskyvyn parantamiseksi voit käyttää palvelinta lähempänä maantieteellistä sijaintiasi:

  • 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

Rajoitukset

  1. Voit suorittaa kyselyn vain viimeisten 30 päivän tiedoista.

  2. Tulokset sisältävät enintään 100 000 riviä.

  3. Suoritusten määrä vuokraajaa kohden on rajoitettu:

    • Ohjelmointirajapintapuhelut: Enintään 45 puhelua minuutissa ja jopa 1 500 puhelua tunnissa.
    • Suoritusaika: 10 minuuttia suoritusaikaa tunnin välein ja 3 tuntia suoritusaikaa päivässä.

  4. Yksittäisen pyynnön enimmäiskäyttöaika on 200 sekuntia.

  5. 429 vastaus edustaa kiintiörajan saavuttamista joko pyyntöjen määrän tai suorittimen mukaan. Lue vastauksen tekstiosa, jotta ymmärrät, mikä raja saavutettiin.

  6. Yksittäisen pyynnön suurin mahdollinen kyselyn tuloskoko ei voi olla yli 124 Mt. Jos pyyntö ylittyy, HTTP 400 -pyyntö ja sanoma "Kyselyn suorittaminen on ylittänyt sallitun tuloskoon. Optimoi kysely rajoittamalla tulosten määrää ja yritä uudelleen" tapahtuu.

Käyttöoikeudet

Tämän ohjelmointirajapinnan kutsumiseen tarvitaan jokin seuraavista käyttöoikeuksista. Lisätietoja ja käyttöoikeuksien valitseminen on artikkelissa Microsoft Defender for Endpoint ohjelmointirajapintoja

Käyttöoikeustyyppi Lupaa Käyttöoikeuden näyttönimi
Sovellus AdvancedQuery.Read.All Run advanced queries
Delegoitu (työpaikan tai oppilaitoksen tili) AdvancedQuery.Read Run advanced queries

Huomautus

Kun hankit tunnuksen käyttäjän tunnistetiedoilla:

  • Käyttäjälle View Data on määritettävä rooli Microsoft Entra ID
  • Käyttäjällä on oltava laitteen käyttöoikeus laiteryhmän asetusten perusteella (lisätietoja on kohdassa Create ja laiteryhmien hallinta)

Laiteryhmän luontia tuetaan Defender for Endpoint -palvelupaketti 1:ssä ja palvelupakettissa 2.

HTTP-pyyntö

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

Pyynnön otsikot

Otsikko Arvo
Lupa Haltija {token}. Pakollinen.
Sisältötyyppi application/json

Pyynnön leipäteksti

Anna pyynnön leipätekstissä JSON-objekti, jolla on seuraavat parametrit:

Parametri Kirjoita Kuvaus
Kyselyn Teksti Suoritettava kysely. Pakollinen.

Vastaus

Jos tämä menetelmä onnistuu, se palauttaa arvon 200 OK ja QueryResponse-objektin vastauksen leipätekstissä.

Esimerkki

Esimerkkipyyntö

Tässä on esimerkki pyynnöstä.

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

Vastausesimerkki

Tässä on esimerkki vastauksesta.

Huomautus

Tässä näkyvä vastausobjekti voidaan katkaista lyhyyden vuoksi. Kaikki ominaisuudet palautetaan todellisesta kutsusta.

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

Vihje

Haluatko tietää lisää? Engage Microsoft security -yhteisön kanssa teknologiayhteisössämme: Microsoft Defender for Endpoint Tech Community.