Cato API - AccountMetrics

Мы настоятельно рекомендуем перед началом использования Cato API ознакомиться с Политикой поддержки Cato API.

Обзор accountMetrics

Запрос accountMetrics помогает анализировать состояние и качество соединений площадок и пользователей SDP с облаком Cato. Эти данные предназначены для трафика внутри DTLS-туннеля между сайтом и облаком Cato.

accountMetrics показывает исторические метрики, статистику и аналитику для аккаунта. Он возвращает данные, аналогичные окну Site Connectivity в приложении управления Cato.

Для реселлерских учетных записей вы можете создать отдельные API-ключи внутри каждой учетной записи клиента, с которой вы подключаетесь к Cato API. Подробную информацию об ограничении скорости и запросе API accountMetrics смотрите в статье Понимание ограничения скорости Cato API.

Работа с градацией ведерок и ограничениями API запросов

Существует максимальный предел в 100,000 возвращаемых элементов на один запрос API accountMetrics. Если запрос достигает этого предела, то никакие дополнительные данные не возвращаются, и отображается сообщение об ошибке.

Cato рассчитывает этот предел, умножая следующие элементы:

• Общее количество сайтов плюс VPN-пользователи

• Количество метрик (API метки/телеметрия)

• Количество ведер

Другими словами, сумма (площадки + VPN пользователи) * (метрики) * (ведра) должна быть меньше 100 000. Например, следующий запрос вызовет ошибку:

• 10 площадок

• 140 VPN пользователей

• 5 метрик

• 150 ведер

(10 + 140) * 5 * 150 = 112 500 элементов в запросе. В этом примере вы можете уменьшить количество ведер для успешного выполнения запроса.

Более подробно о типах API меток см. в статье Cato API - AccountMetrics > Временные ряды.

Расчет минимальной градации для запроса

Этот раздел объясняет, как рассчитать минимальную градацию (размер ведра) на основе временного интервала для запроса.

1. Временное окно - Преобразовать временное окно в секунды

2. Лимит ведра - Рассчитать лимит ведра на основании 100000 / ((сайты + VPN пользователи) * (метрики))

3. Минимальная градация = (временное окно) / (лимит ведра)

Например, первая строка в таблице ниже показывает предел запроса на 7 дней, 100 площадок и VPN пользователей с 5 метриками:

• 7 дней = 604 800 секунд

• 200 ведер = 10000 / (100) * (5)

• 3024 секунды минимальная градация = 604800 / 200

Следующая таблица показывает пример настройки для запроса accountMetrics с минимальной градацией ведра:

Детали для полей accountMetrics

Это детали, которые поля accountMetrics могут вернуть для запроса:

• ID - ID аккаунта

• from - время начала

• to - время окончания

• granularity - размер ведра

• сайты - данные, возвращаемые для каждого сайта (массив с вложенными запросами и полями)

• временные ряды - временные рамки для данных и определяют отношение между сегментами и данными (массив с вложенными запросами и полями)

ID accountMetrics

Поле ID показывает уникальный внутренний идентификатор учетной записи.

Этот ID учетной записи не отображается в Приложении управления Cato, вместо этого это номер в URL для Приложения управления Cato. Например, идентификатор учетной записи равен 26 для следующего URL: https://cc2.catonetworks.com/#!/26/topology.

accountMetrics From

Поле From показывает время начала для данных запроса и определяется в аргументе timeFrame.

accountMetrics To

Поле To показывает время окончания для данных запроса и определяется в аргументе timeFrame.

accountMetrics Granularity

Поле Granularity показывает продолжительность в секундах для одного ведра метрик. Количество ведер определяется в аргументе временные ряды > bucket.

Градация рассчитывается по следующей формуле: timeFrame/ведра. Например, если запрос возвращает пять минут данных (временные рамки) с 60 ведрами, то градация (размер ведра) составляет 5 секунд (300 секунд / 60).

Минимальная градация для ведра составляет 5 секунд. Когда градация ведра меньше 5 секунд, возможно, что для этого ведра не будут возвращены данные.

Дополнительную информацию о поле Granularity см. в статье Работа с accountMetrics > Granularity.

Sites accountMetrics

Поле Sites содержит данные, относящиеся к одной или нескольким площадкам в аккаунте. Вы также можете указать данные для VPN пользователей с их ID пользователей.

Подробнее о поле Sites для accountMetrics см. в статье Cato API - AccountMetrics > Sites.

Временные ряды accountMetrics

Показывает метрики для аккаунта в соответствии с указанными временными рамками (ведра) в запросе и включает историческую статистику и метрики. Эти данные аналогичны полю Site Connectivity в окне приложения управления Cato для каждой площадки.

Подробнее о поле временные ряды для accountMetrics см. в статье Cato API - AccountMetrics > Временные ряды.

Аргументы для accountMetrics

Это аргументы, которые вы можете передать и определить данные, возвращаемые запросом:

• accountID - ID аккаунта

• ID - ID аккаунта (устаревший аргумент)

• timeFrame - время начала и окончания запроса

• groupInterfaces - Объединение аналитики по связям в одно звено (для значения boolean true)

• groupDevices - Для нескольких площадок и одной площадки с несколькими сокетами, объедините аналитику в один сокет (для значения boolean true)

Аргумент accountID accountMetrics

Введите ID аккаунта для данных, возвращенных запросом. Этот аргумент обязателен.

Этот ID учетной записи не отображается в Приложении управления Cato, вместо этого это номер в URL для Приложения управления Cato. Например, идентификатор учетной записи равен 26 для следующего URL: https://cc2.catonetworks.com/#!/26/topology.

аргумент timeFrame accountMetrics

Введите временное окно для данных, возвращаемых запросом. Аргумент имеет формат <тип>.<временное значение>. Этот аргумент обязателен.

Это поддерживаемые параметры для определения временного окна:

• last.<time duration> - Значение <time duration> для типа last задано в соответствии с ISO-8601 и возвращает данные за предыдущий указанный период. Пример:

  • timeFrame = last.PT5M показывает предыдущие 5 минут

  • timeFrame = last.PT2H показывает предыдущие 2 часа

  • timeFrame = last.P1D показывает предыдущий 1 день

  • timeFrame = last.P3M показывает предыдущие 3 месяца

  • timeFrame = last.P1Y показывает предыдущий 1 год

• utc.<краткая спецификация временного окна> - Временное окно содержит дату начала и окончания в формате YY-MM-DD/hh:mm:ss в соответствии с указанным часовым поясом. Вы должны ввести все данные и временные значения для аргумента. Например:

  • timeFrame = utc.2020-02-{11/04:50:00--21/04:50:00} показывает 10 дней аналитических данных с 11 февраля 2020 года 4:50:00 до 21 февраля 2020 года 4:50:00

  • timeFrame = utc.2020-02-11/{04:50:15--16:50:15} показывает 12 часов аналитических данных 11 февраля 2020 года, с 4:50:15 до 16:50:15

  • timeFrame = utc.2020-{02-11/04:50:00--04-11/04:50:00} показывает 2 месяца аналитических данных с 11 февраля 2020 года 4:50:00 до 11 апреля 4:50:00

  • timeFrame = utc.{2019-10-01/04:50:00--2020-02-01/04:50:00} показывает 4 месяца аналитических данных с 1 октября 2019 года 4:50:00 до 11 февраля 2020 года 4:50:00

    Этот формат позволяет настроить временное окно, включающее более одного календарного года

Дополнительную информацию об аргументе timeFrame и поле Granularity см. в статье Работа с accountMetrics > Granularity.

groupInterfaces accountMetrics

Когда аргумент boolean groupInterfaces установлен в значение true, данные для всех интерфейсов агрегируются в один интерфейс.

groupDevices accountMetrics

Когда аргумент boolean groupDevices установлен в значение true, то аналитика для всех сокетов (обычно двух в режиме высокой доступности) агрегируется в один результат. Для лучших результатов агрегированных сокетов мы рекомендуем, чтобы имена и функциональность (например, пункт назначения) для связей на обоих сокетах были постоянными.

Примечание: Этот аргумент обязателен для запросов с несколькими площадками, и единственным допустимым значением для значения groupDevices является true.