API de máquina de offboardOffboard machine API

Aplica-se a:Applies to:

Deseja experimentar o Defender para Ponto de Extremidade?Want to experience Defender for Endpoint? Inscreva-se para uma avaliação gratuita.Sign up for a free trial.

Observação

Se você for um cliente do Governo dos EUA, use os URIs listados no Microsoft Defender for Endpoint para clientes do Governo dos EUA.If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

Dica

Para melhorar o desempenho, você pode usar o servidor mais próximo de sua localização geográfica:For better performance, you can use server closer to your geo location:

  • api-us.securitycenter.microsoft.comapi-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.comapi-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.comapi-uk.securitycenter.microsoft.com

Descrição da APIAPI description

Dispositivo offboard do Defender para Ponto de Extremidade.Offboard device from Defender for Endpoint.

LimitaçõesLimitations

  • Limitações de taxa para essa API são 100 chamadas por minuto e 1500 chamadas por hora.Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

Observação

Esta página se concentra na execução de uma ação de máquina por meio da API.This page focuses on performing a machine action via API. Consulte take response actions on a machine for more information about response actions functionality via Microsoft Defender for Endpoint.See take response actions on a machine for more information about response actions functionality via Microsoft Defender for Endpoint.

Observação

Essa API é suportada Windows 10, versão 1703 e posterior, ou Windows Server 2019 e posterior.This API is supported on Windows 10, version 1703 and later, or Windows Server 2019 and later. Essa API não tem suporte em dispositivos MacOS ou Linux.This API is not supported on MacOS or Linux devices.

PermissõesPermissions

Uma das seguintes permissões é necessária para chamar essa API.One of the following permissions is required to call this API. Para saber mais, incluindo como escolher permissões, consulte Use Defender for Endpoint APIsTo learn more, including how to choose permissions, see Use Defender for Endpoint APIs

Tipo de permissãoPermission type PermissãoPermission Nome de exibição de permissãoPermission display name
AplicativoApplication Machine.OffboardMachine.Offboard 'Máquina de offboard''Offboard machine'
Delegado (conta corporativa ou de estudante)Delegated (work or school account) Machine.OffboardMachine.Offboard 'Máquina de offboard''Offboard machine'

Observação

Ao obter um token usando credenciais de usuário:When obtaining a token using user credentials:

  • O usuário precisa de função de AD 'Administrador Global'The user needs to 'Global Admin' AD role
  • O usuário precisa ter acesso ao dispositivo, com base nas configurações do grupo de dispositivos (Consulte Criar e gerenciar grupos de dispositivos para obter mais informações)The user needs to have access to the device, based on device group settings (See Create and manage device groups for more information)

Solicitação HTTPHTTP request

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

Cabeçalhos de solicitaçãoRequest headers

NomeName TipoType DescriçãoDescription
AutorizaçãoAuthorization Cadeia de caracteresString Portador {token}.Bearer {token}. Obrigatório.Required.
Content-TypeContent-Type stringstring application/json.application/json. Obrigatório.Required.

Corpo da solicitaçãoRequest body

No corpo da solicitação, fornece um objeto JSON com os seguintes parâmetros:In the request body, supply a JSON object with the following parameters:

ParâmetroParameter TipoType DescriçãoDescription
ComentárioComment StringString Comentário para associar à ação.Comment to associate with the action. Obrigatório.Required.

RespostaResponse

Se tiver êxito, este método retornará 201 - Código de resposta criado e Ação do Computador no corpo da resposta.If successful, this method returns 201 - Created response code and Machine Action in the response body.

ExemploExample

SolicitaçãoRequest

Este é um exemplo da solicitação.Here is an example of the request.

POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/offboard
{
  "Comment": "Offboard machine by automation"
}