Lägga till, uppdatera eller ta bort en genomsökningsdefinition

Artikel
05/03/2024

Gäller för:

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

Vill du uppleva Microsoft Defender – hantering av säkerhetsrisker? Läs mer om hur du kan registrera dig för Microsoft Defender – hantering av säkerhetsrisker utvärderingsversion av den offentliga förhandsversionen.

Viktigt

Viss information i den här artikeln gäller en förhyrd produkt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckta eller underförstådda, med avseende på den information som tillhandahålls här.

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:

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

API-beskrivning

API för att lägga till, uppdatera eller ta bort en autentiserad genomsökning.

Begränsningar

Frekvensbegränsningar för det här API:et är 100 anrop per minut och 1 500 anrop per timme.

Du kan publicera på datorer som senast visas enligt din konfigurerade kvarhållningsperiod.

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 Defender för Endpoint-API:er.

Behörighetstyp	Behörighet	Visningsnamn för behörighet
Program	Machine.ReadWrite.All	Läsa och skriva all genomsökningsinformation.
Delegerat (arbets- eller skolkonto)	Machine.Read.Write	Läsa och skriva all genomsökningsinformation.

Obs!

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

Om du vill visa data måste användaren ha minst följande rollbehörighet: ViewData eller TvmViewData (mer information finns i Skapa och hantera roller)
Om du vill redigera data måste användaren ha minst följande rollbehörighet: ManageSecurity (Mer information finns i Skapa och hantera roller)

HTTP-begäran

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

Frågerubriker

Namn	Typ	Beskrivning
Tillstånd	Sträng	Ägaren {token}. Krävs.
Content-Type	sträng	application/json. Krävs.

Frågebrödtext

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

Parameter	Typ	Beskrivning
scanType	Enum	Typ av genomsökning. Möjliga värden är: "Windows", "Network". Krävs.
scanName	Sträng	Namnet på genomsökningen. Krävs.
isActive	Boolesk	Status för om genomsökningen körs aktivt. Krävs.
Mål	Sträng	En kommaavgränsad lista över mål som ska genomsökas, antingen IP-adresser eller värdnamn. Krävs.
intervalInHours	Int	Intervallet då genomsökningen körs. Krävs.
targetType	Sträng	Måltypen i målfältet. Möjliga typer är "IP-adress" eller "Värdnamn". Standardvärdet är IP-adress. Krävs.
scannerAgent	Objekt	maskin-ID. Krävs.
scanAuthenticationParams	Objekt	Ett objekt som representerar autentiseringsparametrarna finns i Objektegenskaper för autentiseringsparametrar för förväntade fält. Den här egenskapen är obligatorisk när du skapar en ny genomsökning och är valfri när du uppdaterar en genomsökning.

Svar

Om det lyckas returnerar den här metoden svarskoden 200 – OK och den nya eller uppdaterade genomsökningsdefinitionen i svarstexten.

Exempelbegäran om att lägga till en ny genomsökning

Här är ett exempel på en begäran som lägger till en ny genomsökning.

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

 {
"scanType": "Windows", 
"scanName": "Test Windows scan", 
"isActive": true, 
"target": "127.0.0.1", 
"intervalInHours": 1, 
"targetType": "Ip",
"scannerAgent": {
    "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
},
"scanAuthenticationParams": { 
    "@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams", 
    "type": "Kerberos", 
    "username": "username", 
    "domain": "password",
    "isGmsaUser": true
    }
}

Exempelsvar

Här är ett exempel på svaret.

 {
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#DeviceAuthenticatedScanDefinitions/$entity",
    "id": "289224fb-1686-472c-9751-5555960854ca",
    "scanType": "Windows",
    "scanName": "Test Windows scan",
    "isActive": true,
    "target": "127.0.0.1",
    "orgId": "0335a792-18d2-424b-aeed-559567054570",
    "intervalInHours": 1,
    "createdBy": "username@test.com",
    "targetType": "Ip",
    "scanAuthenticationParams": null,
    "scannerAgent": {
        "id": "0335a792-18d2-424b-aeed-559567054570_ eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineName": "DESKTOP-TEST",
        "lastSeen": "2023-01-04T09:40:03.2787058Z",
        "assignedApplicationId": "ae4a5cde-b4a1-4b76-8635-458b2cf15752",
        "scannerSoftwareVersion": "7.6.0.0",
        "lastCommandExecutionTimestamp": "2023-01-04T09:33:16Z",
        "mdeClientVersion": "10.8295.22621.1010"
    },
    "latestScan": {
        "status": null,
        "failureReason": null,
        "executionDateTime": null
    }

}

Exempelbegäran om att uppdatera en genomsökning

Här är ett exempel på en begäran som uppdaterar en genomsökning.

PATCH  https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/289224fb-1686-472c-9751-5555960854ca

{
"scanName": "Test Update Windows scan", 
"isActive": false, 
"target": "127.0.0.2,127.0.0.3", 
"intervalInHours": 1, 
"targetType": "Ip",
"scanAuthenticationParams": { 
    "@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams", 
    "type": "Kerberos", 
    "username": "username", 
    "domain": "password",
    "isGmsaUser": true
    }
 }

Svarsexempel