API do computador offboard

Artigo
11/19/2024

Aplica-se a:

Deseja experimentar o Defender para Ponto de Extremidade? Inscreva-se para uma avaliação gratuita.

Observação

Se for um cliente do Governo norte-americano, utilize os URIs listados no Microsoft Defender para Ponto de Extremidade para clientes do Us Government.

Dica

Para um melhor desempenho, pode utilizar o servidor mais próximo da localização geográfica:

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

Descrição da API

Exclusão do dispositivo do Defender para Endpoint.

Limitações

As limitações de taxa para esta API são 100 chamadas por minuto e 1500 chamadas por hora.

Observação

Esta página centra-se na execução de uma ação de computador através da API. Veja tomar medidas de resposta num computador para obter mais informações sobre a funcionalidade de ações de resposta através de Microsoft Defender para Ponto de Extremidade.

Observação

Esta API é suportada no Windows 11, Windows 10, versão 1703 e posterior; no Windows Server 2019 e posterior; e no Windows Server 2012 R2 e Windows Server 2016 ao utilizar o novo agente unificado do Defender para Endpoint.
Esta API não é suportada em dispositivos macOS ou Linux.
A execução da API de exclusão apenas impede a execução do serviço de sensor, mas não remove as informações de inclusão do registo, como faz um script de exclusão.

Permissões

Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, veja Utilizar as APIs do Defender para Endpoint

Tipo de permissão	Permissão	Nome a apresentar da permissão
Application	`Machine.Offboard`	`Offboard machine`
Delegado (conta corporativa ou de estudante)	`Machine.Offboard`	`Offboard machine`

Importante

A Microsoft recomenda que você use funções com o menor número de permissões. Isto ajuda a melhorar a segurança da sua organização. O Administrador Global é uma função altamente privilegiada que deve ser limitada a cenários de emergência quando não for possível usar uma função existente.

Ao obter um token com credenciais de utilizador:

O utilizador tem de ter uma função adequada atribuída (veja Opções de permissão).
O utilizador tem de ter acesso ao dispositivo, com base nas definições do grupo de dispositivos. Para obter mais informações, veja Criar e gerir grupos de dispositivos.

A criação de grupos de dispositivos é suportada no Defender para Endpoint Plano 1 e Plano 2.

Solicitação HTTP

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

O ID do computador pode ser encontrado no URL quando seleciona o dispositivo. Geralmente, é um número alfanumérico de 40 dígitos que pode ser encontrado no URL.

Cabeçalhos de solicitação

Nome	Tipo	Descrição
Autorização	Cadeia de caracteres	{token} de portador. Obrigatório.
Content-Type	string	application/json. Obrigatório.

Corpo da solicitação

No corpo do pedido, forneça um objeto JSON com os seguintes parâmetros:

Parâmetro	Tipo	Descrição
Comentário	String	Comentário a associar à ação. Obrigatório.

Resposta

Se for bem-sucedido, este método devolve 200 - Created response o código e a Ação da Máquina no corpo da resposta.

Exemplo

Solicitação

Eis um exemplo do pedido. Se não houver nenhum comentário JSON adicionado, erros com o código 400.

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

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