API de investigação avançada

  • Artigo

Aplica-se a:

Aviso

Esta API de investigação avançada é uma versão mais antiga com 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. Veja Investigação avançada com a API de segurança do Microsoft Graph

Quer experimentar o Microsoft Defender para Ponto Final? Inscrever-se para uma avaliação gratuita.

Nota

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

Sugestão

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

Limitações

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

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

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

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

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

  6. O tamanho máximo do resultado da consulta de um único pedido não pode exceder os 124 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 Create 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.securitycenter.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.securitycenter.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.