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

  • Статья

Область применения:

Предупреждение

Этот API расширенной охоты является более старой версией с ограниченными возможностями. Более полная версия расширенного API охоты, которая может запрашивать больше таблиц, уже доступна в API безопасности Microsoft Graph. См . раздел Расширенная охота с помощью API безопасности Microsoft Graph

Хотите попробовать Microsoft Defender для конечной точки? Зарегистрироваться для бесплатной пробной версии.

Примечание.

Если вы являетесь клиентом для государственных организаций США, используйте URI, перечисленные в Microsoft Defender для конечной точки для клиентов государственных организаций США.

Совет

Для повышения производительности можно использовать сервер ближе к географическому расположению:

  • 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

Ограничения

  1. Запрос можно выполнить только для данных за последние 30 дней.

  2. Результаты включают не более 100 000 строк.

  3. Количество выполнений ограничено для каждого клиента:

    • Вызовы API: до 45 вызовов в минуту и до 1500 вызовов в час.
    • Время выполнения: 10 минут времени выполнения каждый час и 3 часа в день.

  4. Максимальное время выполнения одного запроса составляет 200 секунд.

  5. 429 Ответ представляет собой достижение предельной квоты по количеству запросов или по ЦП. Прочитайте текст ответа, чтобы понять, какое ограничение достигнуто.

  6. Максимальный размер результата запроса для одного запроса не может превышать 124 МБ. В случае превышения используется недопустимый запрос HTTP 400 с сообщением "Выполнение запроса превысило допустимый размер результата. Оптимизируйте запрос, ограничив количество результатов и повторите попытку".

Разрешения

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

Тип разрешения Разрешение Отображаемое имя разрешения
Приложение AdvancedQuery.Read.All Run advanced queries
Делегированные (рабочая или учебная учетная запись) AdvancedQuery.Read Run advanced queries

Примечание.

При получении маркера с использованием учетных данных пользователя:

  • Пользователю должна быть назначена View Data роль в Microsoft Entra ID
  • Пользователь должен иметь доступ к устройству на основе параметров группы устройств (дополнительные сведения см. в разделе Create и управление группами устройств).

Создание группы устройств поддерживается в Defender для конечной точки плана 1 и плана 2.

HTTP-запрос

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

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

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

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

В тексте запроса укажите объект JSON со следующими параметрами:

Параметр Тип Описание
Запрос Текст Выполняемый запрос. Обязательное поле.

Отклик

В случае успешного выполнения этот метод возвращает значение 200 OK и объект QueryResponse в тексте ответа.

Пример

Пример запроса

Ниже приведен пример запроса.

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

Пример ответа

Ниже приведен пример отклика.

Примечание.

Объект ответа, показанный здесь, может быть усечен для краткости. При фактическом вызове будут возвращены все свойства.

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

Совет

Хотите узнать больше? Engage с сообществом Microsoft Security в нашем техническом сообществе: Microsoft Defender для конечной точки Техническое сообщество.