API del computer offboard

Articolo
11/19/2024

Si applica a:

Si desidera provare Microsoft Defender per endpoint? iscriversi a una versione di valutazione gratuita.

Nota

Se si è un cliente del governo degli Stati Uniti, usare gli URI elencati in Microsoft Defender per endpoint per i clienti del governo degli Stati Uniti.

Consiglio

Per ottenere prestazioni migliori, è possibile usare il server più vicino alla posizione geografica:

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

Descrizione DELL'API

Dispositivo offboard da Defender per endpoint.

Limitazioni

Le limitazioni di frequenza per questa API sono 100 chiamate al minuto e 1.500 chiamate all'ora.

Nota

Questa pagina è incentrata sull'esecuzione di un'azione del computer tramite l'API. Per altre informazioni sulla funzionalità delle azioni di risposta tramite Microsoft Defender per endpoint, vedere Eseguire azioni di risposta in un computer.

Nota

Questa API è supportata in Windows 11, Windows 10, versione 1703 e successive, in Windows Server 2019 e versioni successive e in Windows Server 2012 R2 e Windows Server 2016 quando si usa il nuovo agente unificato per Defender per endpoint.
Questa API non è supportata nei dispositivi macOS o Linux.
L'esecuzione dell'API di offboarding impedisce solo l'esecuzione del servizio sensore, ma non rimuove le informazioni di onboarding dal Registro di sistema come avviene con uno script di offboarding.

Autorizzazioni

Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, incluso come scegliere le autorizzazioni, vedere Usare le API di Defender per endpoint

Tipo di autorizzazione	Autorizzazione	Nome visualizzato autorizzazioni
Applicazione	`Machine.Offboard`	`Offboard machine`
Delegato (account aziendale o dell'istituto di istruzione)	`Machine.Offboard`	`Offboard machine`

Importante

Microsoft consiglia di usare i ruoli con il minor numero di autorizzazioni. Ciò consente di migliorare la sicurezza per l'organizzazione. Amministratore globale è un ruolo con privilegi elevati che deve essere limitato agli scenari di emergenza quando non è possibile usare un ruolo esistente.

Quando si ottiene un token usando le credenziali utente:

All'utente deve essere assegnato un ruolo appropriato (vedere Opzioni di autorizzazione).
L'utente deve avere accesso al dispositivo, in base alle impostazioni del gruppo di dispositivi. Per altre informazioni, vedere Creare e gestire gruppi di dispositivi.

La creazione di gruppi di dispositivi è supportata in Defender per endpoint Piano 1 e Piano 2.

Richiesta HTTP

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

L'ID computer è disponibile nell'URL quando si seleziona il dispositivo. In genere, è un numero alfanumerico a 40 cifre che si trova nell'URL.

Intestazioni di richiesta

Nome	Tipo	Descrizione
Autorizzazione	Stringa	Bearer {token}. Obbligatorio.
Content-Type	stringa	application/json. Obbligatorio.

Corpo della richiesta

Nel corpo della richiesta specificare un oggetto JSON con i parametri seguenti:

Parametro	Tipo	Descrizione
Comment	Stringa	Commento da associare all'azione. Obbligatorio.

Risposta

Se ha esito positivo, questo metodo restituisce 200 - Created response codice e Machine Action nel corpo della risposta.

Esempio

Richiesta

Ecco un esempio della richiesta. Se non è stato aggiunto alcun commento JSON, viene eseguito un errore con il codice 400.

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

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