Чтобы получить информацию о событиях, отправьте запрос к Events API. Например:

При необходимости в такой запрос можно добавить:

• параметры для ограничения времени сбора событий и их объема;
• фильтры для получения конкретных событий.

При успешной обработке запроса в ответе вернется набор событий (events) и значение токена (continuation_token):

Сгенерированный токен можно использовать в следующих запросах для получения новых событий, а также для сохранения параметров фильтрации.

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

Чтобы ограничить время сбора телеметрии и объем поступающих данных, используйте параметры max_timeout и max_events.

Параметр max_timeout

Определяет максимальный период времени, в течение которого внешняя система будет собирать события из очереди.

Формат параметра: PT<целое число>S. Например, при конфигурации max_timeout=PT300S время сбора событий будет ограничено 300 секундами:

Параметр max_events

Определяет максимальное количество событий, которое соберет из очереди внешняя система.

Например, при конфигурации max_events=64000 внешняя система соберет 64000 событий:

Если значение max_events не указано в запросе, KATA автоматически рассчитает его на основе количества устройств с Endpoint Agent.

Параметр continuation_token обеспечивает последовательное получение телеметрии без дублирования событий, полученных в предыдущих запросах.

Events API генерирует значение continuation_token и возвращает его вместе с набором событий после первого запроса. Сохраните этот токен и указывайте его при отправке дальнейших запросов. Например:

Events API вернет только новые события, поскольку токен содержит информацию о том, какие события уже были прочитаны внешней системой и с какой позиции начинать передавать телеметрию.

Полученные внешней системой события могут содержать имя устройства, IP-адрес, версию ОС, тип событий, хеш-суммы файлов MD5 и SHA256, а также другие параметры. Всего в ответе может быть более 100 таких параметров.

Чтобы KATA возвращала только те события, которые отвечают конкретным условиям, используйте фильтры. Например, для получения событий, которые фиксируют изменения в реестре устройства с Endpoint Agent, можно использовать фильтр по полю EventType со значением registry:

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

Использование логических операторов для составления сложных запросов

Чтобы составить сложный запрос с разным набором условий, используйте логические операторы AND, OR, != и другие.

Например, следующий запрос вернет события изменения в реестре устройства с Endpoint Agent или события от устройств только с ОС Windows (поле OsFamily):

Полный список логических операторов можно посмотреть в справке.

Если в первом запросе были указаны параметры фильтрации, информация о них сохраняется в continuation_token. Например, запрос содержит фильтр событий по устройствам с ОС Linux:

Указывать параметры фильтрации в последующих запросах не потребуется. Достаточно передавать только полученный в ответе на этот запрос continuation_token. Например:

Такой запрос позволит продолжить получать телеметрию от устройств с ОС Linux.

Если нужно изменить условия фильтрации, выполните новый запрос без указания параметра continuation_token. В ответе вернется новый токен, который можно будет использовать для следующих запросов.

Значения полей или токен в запросе могут содержать специальные символы, например =, +, /, @, #. Такие символы могут изменять поведение API и влиять на результат вывода.

Чтобы избежать ошибок, выполните URL-кодирование символов одним из способов:

• Используйте сервисы URL-кодирования, например urlencoder.
• Добавьте параметр --data-urlencode в cURL-команду.

Например, для URL-кодирования токена, который содержит специальные символы, добавьте в запрос параметр --data-urlencode:

Специальные символы будут преобразованы в безопасный формат: