Dodawanie, aktualizowanie lub usuwanie definicji skanowania

Artykuł
08/14/2024

Dotyczy:

Chcesz poznać usługę ochrony punktu końcowego w usłudze Microsoft Defender? Utwórz konto, aby skorzystać z bezpłatnej wersji próbnej.

Chcesz skorzystać z zarządzania lukami w zabezpieczeniach usługi Microsoft Defender? Dowiedz się więcej o tym, jak można zarejestrować się w publicznej wersji próbnej usługi Microsoft Defender Vulnerability Management w wersji zapoznawczej.

Ważna

Niektóre informacje zawarte w tym artykule odnoszą się do wersji wstępnej produktu, który może zostać znacznie zmodyfikowany do czasu wydania wersji komercyjnej. Firma Microsoft nie udziela żadnych gwarancji, wyrażonych ani dorozumianych, w odniesieniu do informacji podanych tutaj.

Uwaga

Jeśli jesteś klientem rządowym USA, użyj identyfikatorów URI wymienionych w usłudze Microsoft Defender for Endpoint dla klientów rządowych USA.

Porada

Aby uzyskać lepszą wydajność, możesz użyć serwera bliżej lokalizacji geograficznej:

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
ina.api.security.microsoft.com

Opis interfejsu API

Interfejs API do dodawania, aktualizowania lub usuwania uwierzytelnionego skanowania.

Ograniczenia

Ograniczenia szybkości dla tego interfejsu API to 100 wywołań na minutę i 1500 wywołań na godzinę.

Możesz publikować wpisy na maszynach ostatnio wyświetlanych zgodnie ze skonfigurowanym okresem przechowywania.

Uprawnienia

Do wywołania tego interfejsu API jest wymagane jedno z następujących uprawnień. Aby dowiedzieć się więcej, w tym jak wybrać uprawnienia, zobacz Używanie usługi Defender dla interfejsów API punktu końcowego.

Typ uprawnień	Uprawnienie	Nazwa wyświetlana uprawnień
Aplikacja	Machine.ReadWrite.All	Odczytywanie i zapisywanie wszystkich informacji o skanowaniu.
Delegowane (konto służbowe)	Machine.Read.Write	Odczytywanie i zapisywanie wszystkich informacji o skanowaniu.

Uwaga

Podczas uzyskiwania tokenu przy użyciu poświadczeń użytkownika:

Aby wyświetlić dane, użytkownik musi mieć co najmniej następujące uprawnienia roli: ViewData lub TvmViewData (Zobacz Tworzenie ról i zarządzanie nimi , aby uzyskać więcej informacji)
Aby edytować dane, użytkownik musi mieć co najmniej następujące uprawnienia roli: ManageSecurity (Zobacz Tworzenie ról i zarządzanie nimi , aby uzyskać więcej informacji)

Żądanie HTTP

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

Nagłówki żądań

Name (Nazwa)	Wpisać	Opis
Autoryzacja	Ciąg	Element nośny {token}. Wymagane.
Typ zawartości	ciąg	application/json. Wymagane.

Treść żądania

W treści żądania podaj obiekt JSON z następującymi parametrami:

Parametr	Wpisać	Opis
scanType	Wyliczenie	Typ skanowania. Możliwe wartości to: "Windows", "Network". Wymagane.
scanName	Ciąg	Nazwa skanowania. Wymagane.
isActive	Wartość logiczna	Stan, czy skanowanie jest aktywnie uruchomione. Wymagane.
cel	Ciąg	Rozdzielana przecinkami lista obiektów docelowych do skanowania, adresów IP lub nazw hostów. Wymagane.
intervalInHours	Int	Interwał, w którym jest uruchamiane skanowanie. Wymagane.
targetType	Ciąg	Typ docelowy w polu docelowym. Możliwe typy to "Adres IP" lub "Nazwa hosta". Wartość domyślna to Adres IP. Wymagane.
scannerAgent	Sprzeciwiać się	identyfikator maszyny. Wymagane.
scanAuthenticationParams	Sprzeciwiać się	Obiekt reprezentujący parametry uwierzytelniania, zobacz Właściwości obiektu parametry uwierzytelniania dla oczekiwanych pól. Ta właściwość jest obowiązkowa podczas tworzenia nowego skanowania i jest opcjonalna podczas aktualizowania skanowania.

Odpowiedź

W przypadku powodzenia ta metoda zwraca kod odpowiedzi 200 — OK i nową lub zaktualizowaną definicję skanowania w treści odpowiedzi.

Przykładowe żądanie dodania nowego skanowania

Oto przykład żądania, które dodaje nowe skanowanie.

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

Przykładowa odpowiedź

Oto przykład odpowiedzi.

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

}

Przykładowe żądanie zaktualizowania skanowania

Oto przykład żądania aktualizującego skanowanie.

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

Przykład odpowiedzi