Adicionar ou remover uma etiqueta para um computador
Aplica-se a:
- Plano 1 do Microsoft Defender para Ponto de Extremidade
- Microsoft Defender para Ponto de Extremidade
Deseja experimentar o Microsoft 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
Adiciona ou remove uma etiqueta para um dispositivo específico.
Observação
Se estiver à procura de como etiquetar máquinas em massa através da API, consulte Adicionar ou remover várias etiquetas de computador.
Limitações
Pode publicar em computadores vistos pela última vez de acordo com o período de retenção configurado.
As limitações de taxa para esta API são 100 chamadas por minuto e 1500 chamadas por hora.
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.ReadWrite.All | "Ler e escrever todas as informações do computador" |
| Delegado (conta corporativa ou de estudante) | Machine.ReadWrite | "Ler e escrever informações do computador" |
Observação
Ao obter um token com credenciais de utilizador:
- O utilizador tem de ter, pelo menos, a seguinte permissão de função: "Gerir definição de segurança". Para obter mais informações (consulte Criar e gerir funções para obter mais informações).
- O utilizador precisa de ter acesso ao computador, com base nas definições do grupo de máquinas (consulte Criar e gerir grupos de máquinas para obter mais informações).
Solicitação HTTP
POST https://api.securitycenter.microsoft.com/api/machines/{id}/tags
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 |
|---|---|---|
| Valor | Cadeia de caracteres | O nome da etiqueta. Obrigatório. |
| Ação | Enum | Adicionar ou Remover. Os valores permitidos são: "Adicionar" ou "Remover". Obrigatório. |
Resposta
Se for bem-sucedido, este método devolve o código de resposta 200 - Ok e o Computador atualizado no corpo da resposta.
Exemplo de Solicitação
Eis um exemplo de um pedido que adiciona uma etiqueta de computador.
POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/tags
{
"Value" : "test Tag 2",
"Action": "Add"
}
Para remover a etiqueta do computador, defina a Ação como "Remover" em vez de "Adicionar" no corpo do pedido.
Dica
Você deseja aprender mais? Engage com a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Ponto de Extremidade Tech Community.