API de investigação avançada

  • Aplica-se a: Microsoft Defender for Endpoint

Aviso

A API avançada de caça do Microsoft Defender para Endpoint é antiga e tem capacidades limitadas. Já está disponível uma versão mais abrangente da API de investigação avançada que pode consultar mais tabelas na API de segurança do Microsoft Graph. Para mais informações, consulte Caça avançada usando a API de segurança da Microsoft Graph.

A API avançada de caça Microsoft Defender para Endpoint está a transitar para a API de segurança Microsoft Graph, que inclui capacidades avançadas de caça. A API de segurança Microsoft Graph oferece uma cobertura de dados mais ampla, maior consistência e melhor escalabilidade para fluxos de trabalho de automação e segurança. A reforma começou em janeiro de 2026. Após a conclusão da reforma, a API avançada de caça do Microsoft Defender para Endpoint deixou de funcionar. Para a linha temporal da reforma, veja MC1220762. Para mais informações para ajudar na sua migração, consulte Usar a API de segurança da Microsoft Graph.

Nota

Se for um cliente do Governo dos EUA, utilize os URIs listados no Microsoft Defender para Endpoint para clientes do Us Government.

Sugestão

Para um melhor desempenho, em vez de utilizar api.security.microsoft.com, utilize um servidor mais próximo da geolocalização:

  • 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
  • aea.api.security.microsoft.com

Limitações

  • Só pode executar uma consulta em dados dos últimos 30 dias.

  • Os resultados incluem um máximo de 100 000 linhas.

  • O número de execuções é limitado por inquilino:

    • Chamadas à API: até 45 chamadas por minuto e até 1500 chamadas por hora.
    • Tempo de execução: 10 minutos de tempo de execução a cada hora e 3 horas de tempo de execução por dia.

  • O tempo máximo de execução de um único pedido é de 200 segundos.

  • 429 A resposta representa atingir o limite de quota por número de pedidos ou pela CPU. Leia o corpo da resposta para compreender que limite foi atingido.

  • O tamanho máximo do resultado da consulta de um único pedido não pode exceder os 50 MB. Se for excedido, um Pedido Incorreto HTTP 400 com a mensagem "A execução da consulta excedeu o tamanho do resultado permitido. Otimize a consulta ao limitar o número de resultados e tente novamente" ocorre.

Permissões

É necessária uma das seguintes permissões para chamar esta API. Para saber mais, incluindo como escolher permissões, veja Utilizar Microsoft Defender para Endpoint APIs

Tipo de permissão Permissão Nome a apresentar da permissão
Aplicação AdvancedQuery.Read.All Run advanced queries
Delegado (conta escolar ou profissional) AdvancedQuery.Read Run advanced queries

Nota

Ao obter um token com credenciais de utilizador:

  • O utilizador tem de ter a função View Data atribuída no Microsoft Entra ID.

  • 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.

Pedido HTTP

POST https://api.security.microsoft.com/api/advancedqueries/run

Cabeçalhos de pedido

Cabeçalho Valor
Autorização Portador {token}. Obrigatório.
Tipo de Conteúdo aplicação/json

Corpo do pedido

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

Parâmetro Tipo Descrição
Consulta Text A consulta a executar. Obrigatório.

Resposta

Se for bem-sucedido, este método devolve 200 OK e o objeto QueryResponse no corpo da resposta.

Exemplos:

Exemplo de pedido

Eis um exemplo do pedido.

POST https://api.security.microsoft.com/api/advancedqueries/run

{"Query":"DeviceProcessEvents |where InitiatingProcessFileName =~ 'powershell.exe' |where ProcessCommandLine contains 'appdata'|project Timestamp, FileName, InitiatingProcessFileName, DeviceId|limit 2"}

Exemplo de resposta

Eis um exemplo da resposta.

Nota

O objeto de resposta apresentado aqui pode ser truncado por questões de brevidade. Todas as propriedades serão devolvidas a partir de uma chamada real.

{
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        },
        {
            "Name": "DeviceId",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-02-05T01:10:26.2648757Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        },
        {
            "Timestamp": "2020-02-05T01:10:26.5614772Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe",
            "DeviceId": "10cbf9182d4e95660362f65cfa67c7731f62fdb3"
        }
    ]
}

Sugestão

Quer saber mais? Engage com a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.

  • Last updated on