Offboardcomputer-API

API-Beschreibung

Offboarden des Geräts aus Defender für Endpunkt.

Voraussetzungen

Unterstützte Betriebssysteme

• Diese API wird unter Windows 11, Windows 10 Version 1703 und höher, unterstützt. Windows Server 2019 und höher; Windows Server 2012 R2 und Windows Server 2016, wenn Sie den neuen einheitlichen Agent für Defender für Endpunkt verwenden.

Begrenzungen

• Die Ratenbeschränkungen für diese API sind 100 Aufrufe pro Minute und 1.500 Aufrufe pro Stunde.
• Diese API wird auf macOS- oder Linux-Geräten nicht unterstützt.
• Das Ausführen der Offboarding-API beendet nur die Ausführung des Sensordiensts, entfernt jedoch nicht die Onboardinginformationen aus der Registrierung, wie dies bei einem Offboardingskript der Fall ist.

Berechtigungen

Microsoft empfiehlt die Verwendung von Rollen mit den wenigsten Berechtigungen. Dies trägt zur Verbesserung der Sicherheit für Ihre Organisation bei. Globaler Administrator ist eine hoch privilegierte Rolle, die auf Notfallszenarien beschränkt werden sollte, wenn Sie keine vorhandene Rolle verwenden können.

Beim Abrufen eines Tokens mit Benutzeranmeldeinformationen:

• Dem Benutzer muss eine entsprechende Rolle zugewiesen sein. Weitere Informationen finden Sie unter Berechtigungsoptionen.

• Der Benutzer muss basierend auf den Gerätegruppeneinstellungen Zugriff auf das Gerät haben. Weitere Informationen finden Sie unter Erstellen und Verwalten von Gerätegruppen.

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, einschließlich der Auswahl von Berechtigungen, finden Sie unter Verwenden von Defender für Endpunkt-APIs.

Berechtigungstyp	Permission	Anzeigename der Berechtigung
Application	Machine.Offboard	Offboard machine
Delegiert (Geschäfts-, Schul- oder Unikonto)	Machine.Offboard	Offboard machine

HTTP-Anforderung

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

Die Computer-ID finden Sie in der URL, wenn Sie das Gerät auswählen. Im Allgemeinen handelt es sich um eine 40-stellige alphanumerische Zahl, die in der URL zu finden ist.

Anforderungsheader

Name	Typ	Beschreibung
Authorization	Zeichenfolge	Bearer {token}. Erforderlich.
Content-Type	string	application/json. Erforderlich.

Anforderungstext

Geben Sie im Anforderungstext ein JSON-Objekt mit den folgenden Parametern an:

Parameter	Typ	Beschreibung
Kommentar	Zeichenfolge	Kommentar, der der Aktion zugeordnet werden soll. Erforderlich.

Antwort

Bei erfolgreicher Ausführung gibt die Methode Code und Computeraktion im Antworttext zurück200 - Created response.

Beispiel

Anforderung

Hier sehen Sie ein Beispiel für die Anforderung. Wenn kein JSON-Kommentar hinzugefügt wird, wird ein Fehler mit Code 400ausgegeben.

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

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