Расширенный API охотыAdvanced hunting API

Применяется к: Microsoft Defender для конечной точкиApplies to: Microsoft Defender for Endpoint

Примечание

Если вы клиент правительства США, используйте URL-адреса, указанные в Microsoft Defender для конечных точек для государственных клиентов США.If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

Совет

Для улучшения производительности можно использовать сервер ближе к географическому расположению:For better performance, you can use server closer to your geo location:

  • api-us.securitycenter.microsoft.comapi-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.comapi-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.comapi-uk.securitycenter.microsoft.com

ОграниченияLimitations

  1. Запрос по данным можно выполнить только за последние 30 дней.You can only run a query on data from the last 30 days.

  2. Результаты будут включать не более 100 000 строк.The results will include a maximum of 100,000 rows.

  3. Количество исполняемой работы ограничено для каждого клиента:The number of executions is limited per tenant:

    • Вызовы API: до 45 вызовов в минуту, до 1500 вызовов в час.API calls: Up to 45 calls per minute, up to 1500 calls per hour.
    • Время выполнения: 10 минут времени работы каждый час и 3 часа в день.Execution time: 10 minutes of running time every hour and 3 hours of running time a day.
  4. Максимальное время выполнения одного запроса — 10 минут.The maximal execution time of a single request is 10 minutes.

  5. Ответ 429 будет представлять достижение ограничения квоты по количеству запросов или по ЦП.429 response will represent reaching quota limit either by number of requests or by CPU. Прочитайте текст ответа, чтобы понять, какой предел был достигнут.Read response body to understand what limit has been reached.

РазрешенияPermissions

Для вызова этого API требуется одно из следующих разрешений.One of the following permissions is required to call this API. Дополнительные дополнительные информации, в том числе о выборе разрешений, см. в этой ссылке: Использование API endpoint Defender для Microsoft DefenderTo learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs

Тип разрешенияPermission type РазрешениеPermission Имя отображения разрешенийPermission display name
ПриложениеApplication AdvancedQuery.Read.AllAdvancedQuery.Read.All 'Run advanced queries''Run advanced queries'
Делегированные (рабочая или учебная учетная запись)Delegated (work or school account) AdvancedQuery.ReadAdvancedQuery.Read 'Run advanced queries''Run advanced queries'

Примечание

При получении маркера с помощью учетных данных пользователей:When obtaining a token using user credentials:

  • Пользователю должна быть роль AD "Просмотр данных"The user needs to have 'View Data' AD role
  • Пользователь должен иметь доступ к устройству на основе параметров группы устройств (см. дополнительные сведения о создании и управлении группами устройств).The user needs to have access to the device, based on device group settings (See Create and manage device groups for more information)

HTTP-запросHTTP request

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

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

ЗаголовокHeader ЗначениеValue
АвторизацияAuthorization Bearer {token}.Bearer {token}. Обязательное поле.Required.
Content-TypeContent-Type application/jsonapplication/json

Тело запросаRequest body

В теле запроса поставляем объект JSON со следующими параметрами:In the request body, supply a JSON object with the following parameters:

ПараметрParameter ТипType ОписаниеDescription
ЗапросQuery ТекстText Запрос для выполнения.The query to run. Обязательное поле.Required.

ОткликResponse

В случае успешного выполнения этот метод возвращает 200 ОК и объект QueryResponse в теле отклика.If successful, this method returns 200 OK, and QueryResponse object in the response body.

ПримерExample

ЗапросRequest

Ниже приведен пример запроса.Here is an example of the request.

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"
}
ОткликResponse

Ниже приведен пример отклика.Here is an example of the response.

Примечание

Показанный здесь объект ответа может быть усечен для краткости.The response object shown here may be truncated for brevity. При фактическом вызове будут возвращены все свойства.All of the properties will be returned from an actual call.

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