Offboardcomputer-API

Artikel
11/19/2024

Gilt für:

Möchten Sie Defender für Endpunkt erfahren? Registrieren Sie sich für eine kostenlose Testversion

Hinweis

Wenn Sie ein US Government-Kunde sind, verwenden Sie bitte die URIs, die in Microsoft Defender for Endpoint für US Government-Kunden aufgeführt sind.

Tipp

Um die Leistung zu verbessern, können Sie den Server näher an Ihrem geografischen Standort verwenden:

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

API-Beschreibung

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

Begrenzungen

Die Ratenbeschränkungen für diese API sind 100 Aufrufe pro Minute und 1.500 Aufrufe pro Stunde.

Hinweis

Diese Seite konzentriert sich auf das Ausführen einer Computeraktion über die API. Weitere Informationen zur Funktionalität von Antwortaktionen über Microsoft Defender for Endpoint finden Sie unter Ausführen von Antwortaktionen auf einem Computer.

Hinweis

Diese API wird unter Windows 11, Windows 10, Version 1703 und höher, unter Windows Server 2019 und höher sowie unter Windows Server 2012 R2 und Windows Server 2016 unterstützt, wenn sie den neuen einheitlichen Agent für Defender für Endpunkt verwenden.
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

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	Berechtigung	Anzeigename der Berechtigung
App	`Machine.Offboard`	`Offboard machine`
Delegiert (Geschäfts-, Schul- oder Unikonto)	`Machine.Offboard`	`Offboard machine`

Wichtig

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 (siehe 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.

Die Erstellung von Gerätegruppen wird in Defender für Endpunkt Plan 1 und Plan 2 unterstützt.

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