безопасность: runHuntingQuery

Пространство имен: microsoft.graph.security

Опрашивает указанный набор данных о событиях, действиях или объектах, поддерживаемых Microsoft 365 Defender, для упреждающего поиска конкретных угроз в вашей среде.

Этот метод предназначен для расширенного поиска в Microsoft 365 Defender. Этот метод включает запрос на языке запросов Kusto (KQL). Он указывает таблицу данных в схеме расширенного поиска , а также конвейерную последовательность операторов для фильтрации или поиска этих данных, а также для форматирования выходных данных запроса определенными способами.

Узнайте больше об обнаружении угроз на устройствах, в сообщениях электронной почты, приложениях и удостоверениях. Подробнее о KQL.

Сведения об использовании расширенного поиска на портале Microsoft 365 Defender см. в статье Упреждающий поиск угроз с помощью расширенного поиска в Microsoft 365 Defender.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальное обслуживание	Правительство США L4	Правительство США L5 (DOD)	Китай, обслуживаемый 21Vianet
✅	✅	✅	❌

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более высокий уровень привилегий или разрешений, только если это требуется вашему приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в статье Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения	Разрешения с наименьшим объемом привилегий	Разрешения с более высоким уровнем привилегий
Делегированные (рабочая или учебная учетная запись)	ThreatHunting.Read.All	Недоступно.
Делегированные (личная учетная запись Майкрософт)	Не поддерживается.	Не поддерживается.
Приложение	ThreatHunting.Read.All	Недоступно.

HTTP-запрос

POST /security/runHuntingQuery

Заголовки запросов

Имя	Описание
Авторизация	Bearer {token}. Обязательно. Дополнительные сведения об аутентификации и авторизации.
Content-Type	application/json. Обязательно.

Примечание.

Если в запросе используются символы, отличные от ANSI, например для получения тем сообщений электронной почты с неверно сформированными или похожими символами, используйте application/json; charset=utf-8 в качестве заголовка "Тип содержимого".

Текст запроса

В тексте запроса укажите объект JSON со свойством Query и при желании включите Timespan свойства and workspaceId .

Параметр	Тип	Описание	Пример
Запрос	String	Обязательный. Запрос поиска на языке запросов Kusto (KQL). Дополнительные сведения см. в кратком справочнике по KQL.
Отрезок времени	String	Необязательный параметр. Интервал времени, в течение которого выполняется запрос данных в формате ISO 8601. Значение по умолчанию — 30 дней, то есть если не указано значение startTime, запрос будет возвращаться на 30 дней вперед. Если и в запросе, и в параметре startTime указан временной фильтр, применяется более короткий временной интервал. Например, если в запросе есть фильтр за последние семь дней, а значение startTime указано 10 дней назад, запрос ищет только семь дней назад.
workspaceId	GUID	Необязательный параметр. GUID определенной целевой рабочей области Log Analytics. Если этот параметр опущен, служба использует основную рабочую область вызывающей стороны. Если рабочая область не найдена или недоступна, служба возвращается к основной рабочей области вызывающей стороны.	`00000000-0000-0000-0000-000000000001`

В следующих примерах показаны возможные форматы этого параметра Timespan :

Дата и дата: "2024-02-01T08:00:00Z/2024-02-15T08:00:00Z" — даты начала и окончания.
Duration/endDate: "P30D/2024-02-15T08:00:00Z" — период до даты окончания.
Начало/продолжительность: "2024-02-01T08:00:00Z/P30D" — дата начала и продолжительность.
ISO8601 длительность: "P30D" - Длительность с текущего момента в обратном направлении.
Одиночная дата и время: "2024-02-01T08:00:00Z" — время начала, время окончания по умолчанию текущее время.

Отклик

В случае успеха это действие возвращает код ответа 200 OK и huntingQueryResults в тексте ответа.

Примеры

Пример 1. Запрос с интервалом времени по умолчанию

Запрос

В следующем примере указывается запрос KQL, который выполняет следующие действия:

Изучает таблицу DeviceProcessEvents в схеме расширенного поиска.
Фильтрация при условии, что процесс powershell.exe инициирует событие.
Определяет выходные данные трех столбцов из одной таблицы для каждой строки: Timestamp, FileName, InitiatingProcessFileName.
Сортирует выходные данные по значению Timestamp .
Ограничивает выходные данные двумя записями (две строки).

POST https://graph.microsoft.com/v1.0/security/runHuntingQuery

{
    "Query": "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Security.MicrosoftGraphSecurityRunHuntingQuery;

var requestBody = new RunHuntingQueryPostRequestBody
{
	Query = "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Security.MicrosoftGraphSecurityRunHuntingQuery.PostAsync(requestBody);



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphsecurity "github.com/microsoftgraph/msgraph-sdk-go/security"
	  //other-imports
)

requestBody := graphsecurity.NewRunHuntingQueryPostRequestBody()
query := "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
requestBody.SetQuery(&query) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
microsoftGraphSecurityRunHuntingQuery, err := graphClient.Security().MicrosoftGraphSecurityRunHuntingQuery().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody runHuntingQueryPostRequestBody = new com.microsoft.graph.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody();
runHuntingQueryPostRequestBody.setQuery("DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2");
var result = graphClient.security().microsoftGraphSecurityRunHuntingQuery().post(runHuntingQueryPostRequestBody);


const options = {
	authProvider,
};

const client = Client.init(options);

const huntingQueryResults = {
    Query: 'DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2'
};

await client.api('/security/runHuntingQuery')
	.post(huntingQueryResults);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Security\MicrosoftGraphSecurityRunHuntingQuery\RunHuntingQueryPostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new RunHuntingQueryPostRequestBody();
$requestBody->setQuery('DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2');

$result = $graphServiceClient->security()->microsoftGraphSecurityRunHuntingQuery()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Security

$params = @{
	Query = "DeviceProcessEvents | where InitiatingProcessFileName =~ "powershell.exe" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}

Start-MgSecurityHuntingQuery -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.security.microsoft_graph_security_run_hunting_query.run_hunting_query_post_request_body import RunHuntingQueryPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = RunHuntingQueryPostRequestBody(
	query = "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2",
)

result = await graph_client.security.microsoft_graph_security_run_hunting_query.post(request_body)

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.security.huntingQueryResults",
    "schema": [
        {
            "name": "Timestamp",
            "type": "DateTime"
        },
        {
            "name": "FileName",
            "type": "String"
        },
        {
            "name": "InitiatingProcessFileName",
            "type": "String"
        }
    ],
    "results": [
        {
            "Timestamp": "2024-03-26T09:39:50.7688641Z",
            "FileName": "cmd.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "Timestamp": "2024-03-26T09:39:49.4353788Z",
            "FileName": "cmd.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}

Пример 2. Запрос с необязательным указанным параметром timespan

Запрос

В этом примере указывается запрос KQL и рассматривается таблица deviceProcessEvents в схеме расширенного поиска 60-дневной давности.

POST https://graph.microsoft.com/v1.0/security/runHuntingQuery

{
    "Query": "DeviceProcessEvents",
    "Timespan": "P90D"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Security.MicrosoftGraphSecurityRunHuntingQuery;

var requestBody = new RunHuntingQueryPostRequestBody
{
	Query = "DeviceProcessEvents",
	Timespan = "P90D",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Security.MicrosoftGraphSecurityRunHuntingQuery.PostAsync(requestBody);



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphsecurity "github.com/microsoftgraph/msgraph-sdk-go/security"
	  //other-imports
)

requestBody := graphsecurity.NewRunHuntingQueryPostRequestBody()
query := "DeviceProcessEvents"
requestBody.SetQuery(&query) 
timespan := "P90D"
requestBody.SetTimespan(&timespan) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
microsoftGraphSecurityRunHuntingQuery, err := graphClient.Security().MicrosoftGraphSecurityRunHuntingQuery().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody runHuntingQueryPostRequestBody = new com.microsoft.graph.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody();
runHuntingQueryPostRequestBody.setQuery("DeviceProcessEvents");
runHuntingQueryPostRequestBody.setTimespan("P90D");
var result = graphClient.security().microsoftGraphSecurityRunHuntingQuery().post(runHuntingQueryPostRequestBody);


const options = {
	authProvider,
};

const client = Client.init(options);

const huntingQueryResults = {
    Query: 'DeviceProcessEvents',
    Timespan: 'P90D'
};

await client.api('/security/runHuntingQuery')
	.post(huntingQueryResults);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Security\MicrosoftGraphSecurityRunHuntingQuery\RunHuntingQueryPostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new RunHuntingQueryPostRequestBody();
$requestBody->setQuery('DeviceProcessEvents');
$requestBody->setTimespan('P90D');

$result = $graphServiceClient->security()->microsoftGraphSecurityRunHuntingQuery()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Security

$params = @{
	Query = "DeviceProcessEvents"
	Timespan = "P90D"
}

Start-MgSecurityHuntingQuery -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.security.microsoft_graph_security_run_hunting_query.run_hunting_query_post_request_body import RunHuntingQueryPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = RunHuntingQueryPostRequestBody(
	query = "DeviceProcessEvents",
	timespan = "P90D",
)

result = await graph_client.security.microsoft_graph_security_run_hunting_query.post(request_body)

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "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"
        }
    ]
}

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-08-20

безопасность: runHuntingQuery

Разрешения

HTTP-запрос

Заголовки запросов

Текст запроса

Отклик

Примеры

Пример 1. Запрос с интервалом времени по умолчанию

Запрос

Отклик

Пример 2. Запрос с необязательным указанным параметром timespan

Запрос

Отклик

Обратная связь

Дополнительные ресурсы