Версия: 6.2

Throttling API

Обратите внимание!

Throttling API актуален начиная с версии 6.2.0.

Throttling API позволяет получать, создавать и удалять ручные подавления и исключения для обычных и SP-заданий, а также сбрасывать автоматические подавления.

Автоматическое подавление задается в настройках задания. Как работают автоматическое подавление, ручное подавление и исключения, описано в статье «Подавление в планировщике задач».

Типы заданий

Маршрут операции зависит от типа задания:

Тип задания	Базовый маршрут
Обычное задание	`_core/job_scheduler/jobs/{job_id}`
SP-задание	`_smos/job_sp_meta/{job_id}`

SP-задания

Для управления ручными подавлениями и исключениями SP-задания используйте маршрут _smos/job_sp_meta/{job_id}. Правило, созданное для дочернего задания через маршрут _core/job_scheduler/jobs/{job_id}, сохраняется, но не применяется при выполнении дочернего задания в составе SP-задания.

В маршрутах используются следующие параметры:

Параметр	Синтаксис	Описание
`job_id`	`<string>`	ID задания или SP-задания.
`throttle_id`	`<string>`	ID записи ручного подавления или исключения.

Тело запроса

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

Название	Синтаксис	Обязательный	Описание
`fields`	`<object>`	да	Поля результата поиска и их значения, при совпадении с которыми применяется правило.
`ends_at`	`<string>`	нет	Время окончания действия правила. Если поле не задано, правило действует бессрочно.

Результат соответствует правилу, если совпадают значения всех указанных полей. Если какое-то поле отсутствует в результате, его значением считается строка null.

Ручное подавление или исключение можно создать, только если в настройках задания включено подавление.

Требования к телу запроса

Объект fields должен содержать хотя бы одно поле.

Время окончания можно передать в виде абсолютной даты в формате ISO 8601, например 2030-01-01T00:00:00.000Z, или относительного выражения, например now+7d. Указанное время должно быть в будущем. При сохранении значение преобразуется в Unix-время в секундах. У бессрочной записи поле ends_at отсутствует.

Пример правила со сроком действия:

{
  "fields": {
    "host.name": "host-01"
  },
  "ends_at": "now+7d"
}

Пример бессрочного правила:

{
  "fields": {
    "host.name": "host-01"
  }
}

Структура записи

Операция получения возвращает записи ручных подавлений и исключений со следующими полями:

Название	Синтаксис	Описание
`_meta.id`	`<string>`	ID записи. Используется в операции удаления.
`job_id`	`<string>`	ID задания, для которого создана запись.
`hash`	`<int>`	Служебный хеш значений из `fields`.
`ends_at`	`<long>`	Время окончания действия правила, Unix-время в секундах. У бессрочной записи отсутствует.
`type`	`<string>`	Тип записи: `suppression` — ручное подавление, `exclusion` — исключение.
`origin`	`<string>`	Источник записи. У записей, которые возвращает этот API, — `manual`.
`fields`	`<object>`	Поля и значения правила.
`version`	`<long>`	Версия формата записи.
`sp_info.is_sp_job`	`<bool>`	Признак записи SP-задания.
`sp_info.parent_job_id`	`<string>`	ID SP-задания. Присутствует только у записей SP-заданий.

Получение ручных записей

Операция возвращает не более 1000 действующих записей ручных подавлений и исключений. Автоматически созданные записи в ответ не включаются.

Тип задания	Запрос
Обычное задание	`GET _core/job_scheduler/jobs/{job_id}/throttling`
SP-задание	`GET _smos/job_sp_meta/{job_id}/throttling`

Пример для обычного задания

Пример запроса на получение ручных записей
GET _core/job_scheduler/jobs/job-1/throttling

Пример для SP-задания

Пример запроса на получение ручных записей
GET _smos/job_sp_meta/sp-job-1/throttling

Пример успешного ответа (200):

[
  {
    "_meta": {
      "id": "G7G2aZsBv3Pq8tF2Qw0X"
    },
    "job_id": "job-1",
    "hash": 123456789,
    "ends_at": 1893456000,
    "type": "suppression",
    "origin": "manual",
    "fields": {
      "host.name": "host-01"
    },
    "version": 1,
    "sp_info": {
      "is_sp_job": false
    }
  }
]

Создание ручного подавления

Операция создает правило ручного подавления или продлевает существующее.

Тип задания	Запрос
Обычное задание	`POST _core/job_scheduler/jobs/{job_id}/throttling`
SP-задание	`POST _smos/job_sp_meta/{job_id}/throttling`

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

Пример для обычного задания

Пример запроса на создание ручного подавления
POST _core/job_scheduler/jobs/job-1/throttling
{
  "fields": {
    "host.name": "host-01"
  },
  "ends_at": "now+7d"
}

Пример для SP-задания

Пример запроса на создание ручного подавления
POST _smos/job_sp_meta/sp-job-1/throttling
{
  "fields": {
    "host.name": "host-01"
  },
  "ends_at": "now+7d"
}

Пример успешного ответа (200):

{
  "message": "throttling was created successfully",
  "id": "G7G2aZsBv3Pq8tF2Qw0X"
}

Поле id содержит идентификатор созданной или продленной записи.

Создание исключения

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

Тип задания	Запрос
Обычное задание	`POST _core/job_scheduler/jobs/{job_id}/throttling/exclusions`
SP-задание	`POST _smos/job_sp_meta/{job_id}/throttling/exclusions`

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

Пример для обычного задания

Пример запроса на создание исключения
POST _core/job_scheduler/jobs/job-1/throttling/exclusions
{
  "fields": {
    "host.name": "host-01"
  }
}

Пример для SP-задания

Пример запроса на создание исключения
POST _smos/job_sp_meta/sp-job-1/throttling/exclusions
{
  "fields": {
    "host.name": "host-01"
  }
}

Удаление ручной записи

Операция удаляет запись ручного подавления или исключения по ее идентификатору. Автоматическую запись удалить с помощью этой операции нельзя.

Тип задания	Запрос
Обычное задание	`DELETE _core/job_scheduler/jobs/{job_id}/throttling/{throttle_id}`
SP-задание	`DELETE _smos/job_sp_meta/{job_id}/throttling/{throttle_id}`

Пример для обычного задания

Пример запроса на удаление ручной записи
DELETE _core/job_scheduler/jobs/job-1/throttling/G7G2aZsBv3Pq8tF2Qw0X

Пример для SP-задания

Пример запроса на удаление ручной записи
DELETE _smos/job_sp_meta/sp-job-1/throttling/G7G2aZsBv3Pq8tF2Qw0X

Пример успешного ответа (200):

"Throttle entry was deleted"

Сброс автоматических подавлений

Для обычного задания операция удаляет его автоматические записи, для SP-задания — автоматические записи всех дочерних заданий. Ручные подавления и исключения сохраняются.

Тип задания	Запрос
Обычное задание	`POST _core/job_scheduler/jobs/{job_id}/reset_throttling`
SP-задание	`POST _smos/job_sp_meta/{job_id}/reset_throttling`

Тело запроса не требуется.

Пример для обычного задания

Пример запроса на сброс автоматических подавлений
POST _core/job_scheduler/jobs/job-1/reset_throttling

Пример для SP-задания

Пример запроса на сброс автоматических подавлений
POST _smos/job_sp_meta/sp-job-1/reset_throttling

Пример успешного ответа (200):

"Throttling for job with id 'job-1' was reset"

Типы заданий​

Тело запроса​

Структура записи​

Получение ручных записей​

Создание ручного подавления​

Создание исключения​

Удаление ручной записи​

Сброс автоматических подавлений​

Типы заданий

Тело запроса

Структура записи

Получение ручных записей

Создание ручного подавления

Создание исключения

Удаление ручной записи

Сброс автоматических подавлений