Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Aviso
Essa API de busca avançada é uma versão mais antiga com recursos limitados. Uma versão mais abrangente da Advanced Hunting API está disponível na Microsoft Graph Security API. Para obter mais informações, consulte Busca avançada usando Microsoft Graph API de segurança.
A API avançada de caça Microsoft Defender XDR está em transição para a API de segurança Microsoft Graph, que oferece cobertura de dados mais ampla, maior consistência e maior escalabilidade para fluxos de automação e segurança. A aposentadoria começou em janeiro de 2026. Após a aposentadoria concluída, a API avançada de caça do Microsoft Defender XDR deixa de funcionar mais. Para a linha do tempo de desativação, consulte MC1220762. Para orientações sobre migração, veja Usar a API de segurança da Microsoft Graph.
Importante
Algumas informações estão relacionadas a produtos pré-lançados que podem ser substancialmente modificados antes de seu lançamento comercial. A Microsoft não faz garantias, expressas ou implícitas, quanto às informações fornecidas aqui.
A caça avançada é uma ferramenta de caça a ameaças que utiliza consultas especialmente construídas para examinar dados de eventos no Microsoft Defender. Você pode usar consultas avançadas de busca para inspecionar atividades incomuns, detectar possíveis ameaças e até responder a ataques. A API de busca avançada permite consultar dados de eventos de forma programática.
Cotas e alocação de recursos
As condições a seguir estão relacionadas a todas as consultas.
- As consultas exploram e retornam dados dos últimos 30 dias.
- Os resultados podem retornar até 100.000 linhas.
- Você pode fazer pelo menos 45 chamadas por minuto por locatário. O número de chamadas varia por locatário com base em seu tamanho.
- Cada locatário recebe recursos de CPU com base no tamanho do locatário. As consultas serão bloqueadas se o locatário tiver atingido 100% dos recursos alocados até depois do próximo ciclo de 15 minutos. Para evitar consultas bloqueadas devido ao consumo excessivo, siga as orientações em Otimizar suas consultas para evitar o cumprimento das cotas de CPU.
- Se uma única solicitação for executada por mais de três minutos, ela atingirá o tempo limite e retornará um erro.
- Um
429código de resposta HTTP indica que você alcançou os recursos de CPU alocados, seja pelo número de solicitações enviadas ou pelo tempo de execução alocado. Leia o corpo da resposta para entender o limite atingido.
Permissões
Uma das permissões a seguir é necessária para chamar a API de busca avançada. Para saber mais, incluindo como escolher permissões, consulte Acessar as APIs de Proteção de Microsoft Defender.
| Tipo de permissão | Permissão | Nome de exibição da permissão |
|---|---|---|
| Application | AdvancedHunting.Read.All | Executar consultas avançadas |
| Delegado (conta corporativa ou de estudante) | AdvancedHunting.Read | Executar consultas avançadas |
Observação
Ao obter um token usando credenciais de usuário:
- O usuário precisa ter a função 'Exibir Dados'.
- O usuário precisa ter acesso ao dispositivo, com base nas configurações do grupo de dispositivos.
solicitação HTTP
POST https://api.security.microsoft.com/api/advancedhunting/run
Cabeçalhos de solicitação
| Cabeçalho | Valor |
|---|---|
| Autorização | Portador {token} Observação: obrigatório |
| Content-Type | application/json |
Corpo da solicitação
No corpo da solicitação, forneça um objeto JSON com os seguintes parâmetros:
| Parâmetro | Tipo | Descrição |
|---|---|---|
| Consultar | Texto | A consulta a ser executada. (obrigatório) |
Resposta
Se for bem-sucedido, esse método retornará 200 OKe um objeto QueryResponse no corpo da resposta.
O objeto de resposta contém três propriedades de nível superior:
- Estatísticas - Um dicionário de estatísticas de desempenho de consulta.
- Esquema - O esquema da resposta, uma lista de Name-Type pares para cada coluna.
- Resultados - Uma lista de eventos avançados de busca.
Exemplo
No exemplo a seguir, um usuário envia a consulta abaixo e recebe um objeto de resposta da API contendo Stats, Schema, e Results.
Consultar
{
"Query":"DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}
Objeto de resposta
{
"Stats": {
"ExecutionTime": 4.621215,
"resource_usage": {
"cache": {
"memory": {
"hits": 773461,
"misses": 4481,
"total": 777942
},
"disk": {
"hits": 994,
"misses": 197,
"total": 1191
}
},
"cpu": {
"user": "00:00:19.0468750",
"kernel": "00:00:00.0156250",
"total cpu": "00:00:19.0625000"
},
"memory": {
"peak_per_node": 236822432
}
},
"dataset_statistics": [
{
"table_row_count": 2,
"table_size": 102
}
]
},
"Schema": [
{
"Name": "Timestamp",
"Type": "DateTime"
},
{
"Name": "FileName",
"Type": "String"
},
{
"Name": "InitiatingProcessFileName",
"Type": "String"
}
],
"Results": [
{
"Timestamp": "2020-08-30T06:38:35.7664356Z",
"FileName": "conhost.exe",
"InitiatingProcessFileName": "powershell.exe"
},
{
"Timestamp": "2020-08-30T06:38:30.5163363Z",
"FileName": "conhost.exe",
"InitiatingProcessFileName": "powershell.exe"
}
]
}
Artigos relacionados
Dica
Você deseja aprender mais? Participe da comunidade de Segurança da Microsoft em nossa Tech Community: Tech Community do Microsoft Defender XDR.