Obter máquina por API de ID

Artigo
02/14/2025

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

Obtém o Computador específico pelo respetivo ID de dispositivo ou nome do computador.

Limitações

Pode ver os dispositivos pela última vez de acordo com a política de retenção configurada.
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 Microsoft Defender para Ponto de Extremidade APIs

Tipo de permissão	Permissão	Nome a apresentar da permissão
Application	Machine.Read.All	"Ler todos os perfis de máquina"
Application	Machine.ReadWrite.All	"Ler e escrever todas as informações do computador"
Delegado (conta corporativa ou de estudante)	Machine.Read	"Ler 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: "Ver Dados" (Consulte Criar e gerir funções para obter mais informações)
O utilizador precisa de ter acesso ao dispositivo, com base nas definições do grupo de dispositivos (consulte Criar e gerir grupos de dispositivos para obter mais informações)

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

Solicitação HTTP

GET /api/machines/{id}

Cabeçalhos de solicitação

Nome	Tipo	Descrição
Autorização	Cadeia de caracteres	{token} de portador. Obrigatório.

Corpo da solicitação

Vazio

Resposta

Se tiver êxito e o dispositivo existir – 200 OK com a entidade do computador no corpo. Se o computador com o ID especificado não tiver sido encontrado – 404 Não Encontrado.

Exemplo

Exemplo de solicitação

Eis um exemplo do pedido.

GET https://api.security.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07

Exemplo de resposta

Veja um exemplo de resposta.

HTTP/1.1 200 OK
Content-type: application/json
{
    "@odata.context": "https://api.security.microsoft.com/api/$metadata#Machine",
    "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
    "computerDnsName": "mymachine1.contoso.com",
    "firstSeen": "2018-08-02T14:55:03.7791856Z",
    "lastSeen": "2018-08-02T14:55:03.7791856Z",
    "osPlatform": "Windows10" "Windows11",
    "version": "1709",
    "osProcessor": "x64",
    "lastIpAddress": "172.17.230.209",
    "lastExternalIpAddress": "167.220.196.71",
    "osBuild": 18209,
    "healthStatus": "Active",
    "rbacGroupId": 140,
    "rbacGroupName": "The-A-Team",
    "riskScore": "Low",
    "exposureLevel": "Medium",
    "isAadJoined": true,
    "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
    "machineTags": [ "test tag 1", "test tag 2" ]
}