Interfejs API maszyny odłączaowej

Opis interfejsu API

Odłącz urządzenie od usługi Defender for Endpoint.

Wymagania wstępne

Obsługiwane systemy operacyjne

System operacyjny	Obsługiwane wersje
Klient systemu Windows	Windows 11 i Windows 10, wersja 1703 i późniejsze
Serwer z systemem Windows	Windows Server 2019 i nowsze; Windows Server 2012 R2 i Windows Server 2016 przy użyciu nowego, zunifikowanego agenta dla Defender for Endpoint
macOS	macOS 14 i późniejsze
Linux	Obsługiwane dystrybucje Linux

Ograniczenia

• Ograniczenia szybkości dla tego interfejsu API to 100 wywołań na minutę i 1500 wywołań na godzinę.
• Na urządzeniach z Windows uruchomienie API offboardingu zatrzymuje tylko usługę sensorów. Nie usuwa on informacji o wdrożeniu z rejestru, tak jak robi to skrypt offboardingowy.

Uprawnienia

Firma Microsoft rekomenduje używanie ról z najmniejszą liczbą uprawnień. Pomaga to zwiększyć bezpieczeństwo organizacji. Administrator globalny to rola o wysokim poziomie uprawnień, która powinna być ograniczona do scenariuszy awaryjnych, gdy nie można użyć istniejącej roli.

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

• Użytkownik musi mieć przypisaną odpowiednią rolę. Aby uzyskać więcej informacji, zobacz: Opcje uprawnień.

• Użytkownik musi mieć dostęp do urządzenia na podstawie ustawień grupy urządzeń. Aby uzyskać więcej informacji, zobacz: Tworzenie grup urządzeń i zarządzanie nimi.

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 Korzystanie z usługi Defender dla interfejsów API punktu końcowego

Typ uprawnień	Uprawnienie	Nazwa wyświetlana uprawnień
Aplikacja	Machine.Offboard	Offboard machine
Delegowane (konto służbowe)	Machine.Offboard	Offboard machine

żądanie HTTP

POST https://api.security.microsoft.com/api/machines/{id}/offboard

Identyfikator komputera można znaleźć w adresie URL po wybraniu urządzenia. Ogólnie rzecz biorąc, jest to 40-cyfrowy numer alfanumeryczny, który można znaleźć w adresie URL.

Nagłówki żądań

Name (Nazwa)	Typ	Opis
Autoryzacji	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	Typ	Opis
Komentowanie	Ciąg	Komentarz do skojarzenia z akcją. Wymagane.

Odpowiedzi

W przypadku powodzenia ta metoda zwraca 200 - Created response kod i akcję maszyny w treści odpowiedzi.

Przykład

Żądanie

Oto przykład żądania. Jeśli nie dodano komentarza JSON, występuje błąd z kodem 400.

POST https://api.security.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/offboard

{
  "Comment": "Offboard machine by automation"
}