Версия: 6.2

Job Scheduler API

Job

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

Структура Job

Название	Синтаксис	Описание
name	`<string>`	Название задачи.
title	`<string>`	Заголовок задачи.
description	`<string>`	Описание задачи.
throttle	`<object>`	Параметры подавления. Подробнее см. в разделе Throttle.
actions	`<array>`	Список активных действий. Каждое действие — объект. Подробнее см. в разделе Actions API.
throttle	`<object>`	Параметры подавления. Подробнее см. в разделе Throttle.
actions	`<array>`	Список активных действий. Каждое действие — объект. Подробнее см. в разделе Actions API.
global_params	`<object>`	Глобальные параметры задачи в формате `ключ - значение`.
search	`<object>`	Параметры поиска при выполнении задания. Подробнее см. в разделе Search.
run_with_roles	`<array>`	Список ролей, которые могут выполнять задачу.
schedule	`<object>`	Расписание выполнения задачи (Подробнее Schedule).
enabled	`<bool>`	Состояние задачи (`включена`, `выключена`).
lock_duration_seconds	`<int>`	Интервал времени между выполнением текущего и следующего запроса.
jitter	`<float>`	Случайное смещение времени.
_permissions	`<object>`	Права доступа задачи.

Throttle

Название	Синтаксис	Описание
enabled	`<bool>`	Состояние подавления: `true` — включено, `false` — выключено. Значение по умолчанию — `false`.
time	`<string>`	Время действия автоматического подавления.
fields	`<array>`	Список полей для подавления. Названия полей передаются строками.

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

Поле throttle.enabled актуально начиная с версии 6.2.0.

Подавление

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

Подробнее механизм подавления описан в статье «Подавление в планировщике задач». Операции с ручными подавлениями и исключениями описаны в статье «Throttling API».

Schedule

Название	Синтаксис	Описание
cron	`<object>`	Расписание на основе Cron.
interval	`<object>`	Расписание на основе интервала.

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

Параметры cron и interval взаимоисключающие. Если указано поле cron, поле interval должно отсутствовать, и наоборот.

Cron

Название	Синтаксис	Описание
expression	`<string>`	Cron-выражение.
timezone	`<string>`	Часовой пояс.

Interval

Название	Синтаксис	Описание
start_time	`<string>`	Время, с которого начинается отсчет интервалов.
period	`<int>`	Длина интервала.
unit	`<string>`	Единица измерения, например `MINUTES`, `HOURS` или `DAYS`.

Search

Название	Синтаксис	Описание
query	`<string>`	Запрос.
time_field	`<string>`	Имя поля, в котором хранится временная метка.
earliest	`<string>`	Начальная временная метка поиска.
latest	`<string>`	Конечная временная метка поиска.

CRUD для Job

Получение списка всех задач

GET _core/job_scheduler/jobs/

к сведению

Начиная с версии 6.1.0 запрос на получение списка всех задач планировщика возвращает статистику последних пяти запусков каждой задачи.

Статистика запусков содержит следующие поля:

Название	Синтаксис	Описание
message	`<string>`	Текстовое сообщение о результате выполнения задачи.
execution_time	`<number>`	Время выполнения задачи в миллисекундах.
status	`<string>`	Статус выполнения задачи.
start_time	`<string>`	Временная метка начала выполнения задачи.

Получение задачи по ID

GET _core/job_scheduler/jobs/{job_id}

к сведению

Начиная с версии 6.1.0 при запросе задания по ID возвращается статистика пяти последних его запусков.

Статистика запусков содержит следующие поля:

Название	Синтаксис	Описание
message	`<string>`	Текстовое сообщение о результате выполнения задачи.
execution_time	`<number>`	Время выполнения задачи в секундах.
status	`<string>`	Статус выполнения задачи.
start_time	`<string>`	Временная метка начала выполнения задачи.

Добавление новой задачи

POST _core/job_scheduler/jobs/
{
  "title": "Тестирование Email c smtpConnection",
  "description": "test description",
  "throttle": {
    "enabled": true,
    "time": "5m",
    "fields": ["host.name"]
  },
  "actions": [
    {
      "script": {
        "context": "/app/opensearch/utils/python/bin/python3 /app/opensearch/utils/scripts/file_write_script.py",
        "is_once": false,
        "local_params": {}
      }
    }
  ],
  "global_params": {
    "key": "value"
  },
  "search": {
    "sme": {
      "query": "source internal_audit-* qsize=5;",
      "time_field": "@timestamp",
      "earliest": "now-24h",
      "latest": "now"
    }
  },
  "run_with_roles": [],
  "name": "Testirovanie_Email_c_smtpConnection",
  "schedule": {
    "cron": {
      "expression": "* * * * *",
      "timezone": "Europe/Moscow"
    }
  },
  "enabled": false,
  "lock_duration_seconds": 30,
  "_permissions": {
    "owner": "admin",
    "read": {
      "roles": [],
      "users": []
    },
    "write": {
      "roles": [],
      "users": []
    }
  }
}

Обновление задачи

PUT _core/job_scheduler/jobs/{job_id}
{
  "title": "Тестирование Email c smtpConnection",
  "throttle": {
    "enabled": true,
    "time": "5m",
    "fields": ["host.name"]
  },
  "actions": [
    {
      "script": {
        "context": "/app/opensearch/utils/python/bin/python3 /app/opensearch/utils/scripts/file_write_script.py",
        "is_once": false,
        "local_params": {}
      }
    }
  ],
  "global_params": {},
  "search": {
    "sme": {
      "query": "source internal_audit-* qsize=5;",
      "time_field": "@timestamp",
      "earliest": "now-24h",
      "latest": "now"
    }
  },
  "run_with_roles": [],
  "name": "Testirovanie_Email_c_smtpConnection",
  "schedule": {
    "cron": {
      "expression": "* * * * *",
      "timezone": "Europe/Moscow"
    }
  },
  "enabled": false,
  "lock_duration_seconds": 30,
  "_permissions": {
    "owner": "admin",
    "read": {
      "roles": [],
      "users": []
    },
    "write": {
      "roles": [],
      "users": []
    }
  }
}

Удаление задачи

DELETE _core/job_scheduler/jobs/{job_id}

Запись в БД

Чтобы настроить активное действие Запись в БД, сначала создайте пользователей JDBC и соединения.

JDBC User

Название	Синтаксис	Описание
name	`<string>`	Произвольное название для идентификации JDBC-пользователя.
username	`<string>`	Логин пользователя, используемый для авторизации в базе данных.
password_id	`<string>`	Идентификатор ключа в Keystore. Для получения пароля используется ключ с префиксом `jobscheduler.jdbc.password.`.

Пример
{
  "name": "name",
  "username": "username",
  "password_id": "passwordId"
}

Connection

Название	Синтаксис	Описание
name	`<string>`	Название базы данных.
driver	`<object>`	Драйвер базы данных (например, `postgres`, `clickhouse`).
host	`<string>`	Адрес хоста, на котором находится база данных (например, "localhost" или IP-адрес).
port	`<string>`	Номер порта, используемого для подключения к базе данных.
db	`<string>`	Имя базы данных, к которой осуществляется подключение.

Пример
{
  "name": "myDatabase",
  "driver": "postgres",
  "host": "localhost",
  "port": "5432",
  "db": "myDbName"
}

CRUD для JDBC User

Получение списка всех пользователей

GET _core/job_scheduler/jdbc_user/

Получение пользователя по ID

GET _core/job_scheduler/jdbc_user/{jdbc_user_id}

Добавление нового пользователя

POST _core/job_scheduler/jdbc_user/
{
  "name": "name",
  "username": "username",
  "password_id": "passwordId"
}

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

Параметр password_id должен содержать не сам пароль, а идентификатор ключа в Keystore. Ключ должен иметь префикс jobscheduler.jdbc.password..

к сведению

В параметре name укажите произвольное имя JDBC-пользователя, а в username — логин для подключения к базе данных.

Обновление пользователя

PUT _core/job_scheduler/jdbc_user/{jdbc_user_id}
{
  "name": "name",
  "username": "username",
  "password_id": "passwordId"
}

Удаление пользователя

DELETE _core/job_scheduler/jdbc_user/{jdbc_user_id}

Установка пароля пользователя

POST _core/keystore/jobscheduler.jdbc.password.{password_id}
{
  "value" : "password"
}

CRUD для Connection

Получение списка всех соединений

GET _core/job_scheduler/jdbc_connection/

Получение соединения по ID

GET _core/job_scheduler/jdbc_connection/{connection_id}

Добавление нового соединения

POST _core/job_scheduler/jdbc_connection
{
  "name": "myDatabase",
  "driver": "postgres",
  "host": "localhost",
  "port": "5432",
  "db": "myDbName"
}

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

Параметр driver, указывающий на то, какой JDBC-драйвер будет использоваться, может принимать следующие значения:

postgres
mssql
oracle
hive
sap
clickhouse

к сведению

В параметре name укажите произвольное имя для идентификации базы данных, а в db — ее точное системное имя для подключения.

Обновление соединения

PUT _core/job_scheduler/jdbc_connection/{connection_id}
{
  "name": "myDatabase",
  "driver": "postgres",
  "host": "localhost",
  "port": "5432",
  "db": "myDbName"
}

Удаление соединения

DELETE _core/job_scheduler/jdbc_connection/{connection_id}

Mail

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

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

Если в Mail Action не указан smtp_id, настройки отправителя берутся из индекса .sm_settings.

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

Если в Mail Action не указан параметр recipient_group_id, получателем будет пользователь, указанный в параметре to.

Recipient

Название	Синтаксис	Описание
name	`<string>`	Имя получателя.
description	`<string>`	Описание получателя.
type	`<string>`	Тип адреса.
address	`<string>`	Адрес электронной почты получателя.

Пример
{
  "name": "name",
  "description": "description",
  "type": "EMAIL",
  "address": "test@test.ru"
}

Recipient Group

Название	Синтаксис	Описание
name	`<string>`	Имя группы получателей.
description	`<string>`	Описание группы получателей.
recipient_ids	`<array>`	ID получателей, которые записаны в индекс получателей.
recipient_emails	`<array>`	Список адресов получателей, которые не записаны в индекс получателей.

Пример
{
  "name": "name",
  "description": "description",
  "recipient_ids": ["id1", "id2"],
  "recipient_emails": ["test@test.ru", "test2@test.ru"]
}

SMTP

SMTP имеет структуру:

Название	Синтаксис	Описание
name	`<string>`	Имя SMTP-сервера.
description	`<string>`	Описание SMTP-сервера.
host	`<string>`	Адрес хоста SMTP-сервера.
port	`<string>`	Порт, на котором работает SMTP-сервер (например, 12345).
user	`<string>`	Имя пользователя для аутентификации на SMTP-сервере.
user_email	`<string>`	Адрес электронной почты пользователя, связанный с учетной записью SMTP-сервера.
password_id	`<string>`	Идентификатор ключа в Keystore. Для получения пароля используется ключ с префиксом `jobscheduler.email.password.`.
timeout	`<int>`	Тайм-аут подключения и ожидания каждого ответа SMTP-сервера в миллисекундах. Значение по умолчанию — `5000`. Значение `0` отключает ограничение времени ожидания. Отрицательное значение отклоняется при сохранении.
proto	`<string>`	Протокол, используемый для подключения к SMTP-серверу (например, `ssl`).

Пароль системной SMTP-конфигурации

Если у системной SMTP-конфигурации не указан password_id, пароль загружается из Keystore по ключу jobscheduler.email.pass. Если password_id указан, используется ключ jobscheduler.email.password.{password_id}.

Пример
{
  "name": "name",
  "description": "description",
  "host": "host",
  "port": "12345",
  "user": "user",
  "user_email": "test@test.su",
  "password_id": "passwordId",
  "timeout": 5000,
  "proto": ""
}

CRUD для Recipient

Получение списка всех получателей

GET _core/job_scheduler/recipients

Получение получателя по ID

GET _core/job_scheduler/recipients/{recipient_id}

Добавление нового получателя

POST _core/job_scheduler/recipients
{
  "name": "name",
  "description": "description",
  "type": "EMAIL",
  "address": "test@test.ru"
}

Обновление получателя

PUT _core/job_scheduler/recipients/{recipient_id}
{
  "name": "name",
  "description": "description",
  "type": "EMAIL",
  "address": "test@test.ru"
}

Удаление получателя

DELETE _core/job_scheduler/recipients/{recipient_id}

CRUD для Recipient Group

Получение списка всех групп получателей

GET _core/job_scheduler/recipient_groups

Получение группы получателей по ID

GET _core/job_scheduler/recipient_groups/{recipient_group_id}

Добавление новой группы получателей

POST _core/job_scheduler/recipient_groups
{
  "name": "name",
  "description": "description",
  "recipient_ids": [
    "id1",
    "id2"
  ],
  "recipient_emails": [
    "test@test.ru",
    "test2@test.ru"
  ]
}

Обновление группы получателей

PUT _core/job_scheduler/recipient_groups
{
  "name": "name",
  "description": "description",
  "recipient_ids": [
    "id1",
    "id2"
  ],
  "recipient_emails": [
    "test@test.ru",
    "test2@test.ru"
  ]
}

Удаление группы получателей

DELETE _core/job_scheduler/recipient_groups/{recipient_group_id}

CRUD для SMTP

Получение списка всех SMTP

GET _core/job_scheduler/smtp

Получение SMTP по ID

GET _core/job_scheduler/smtp/{smtp_id}

Добавление нового SMTP

POST _core/job_scheduler/smtp
{
  "name": "name",
  "description": "description",
  "host": "host",
  "port": "12345",
  "user": "user",
  "user_email": "test@test.su",
  "password_id": "passwordId",
  "timeout": 5000,
  "proto": ""
}

При успешном создании ответ содержит идентификатор SMTP-конфигурации в поле id:

{
  "message": "Config with id 'CSksd1SABJ12O_DKcsu4BP' CREATED",
  "id": "CSksd1SABJ12O_DKcsu4BP"
}

Обновление SMTP

PUT _core/job_scheduler/smtp/{smtp_id}
{
  "name": "name",
  "description": "description",
  "host": "host",
  "port": "12345",
  "user": "user",
  "user_email": "test@test.su",
  "password_id": "passwordId",
  "timeout": 5000,
  "proto": ""
}

Удаление SMTP

DELETE _core/job_scheduler/smtp/{smtp_id}

Проверка подключения к SMTP-серверу

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

Во время проверки письмо не отправляется: выполняются подключение к SMTP-серверу, аутентификация AUTH, проверка адреса отправителя командой MAIL FROM и сброс почтовой транзакции командой RSET.

При проверке подключения ожидание каждой сетевой операции — подключения или ответа на команду — длится не более 300 000 мс. Общего ограничения продолжительности проверки нет.

Проверка сохраненной SMTP-конфигурации

POST /_core/job_scheduler/smtp/test_smtp/{id}

id — идентификатор сохраненной SMTP-конфигурации. Пароль загружается из Keystore по ее password_id.

Проверка SMTP-конфигурации по параметрам из тела запроса

POST /_core/job_scheduler/smtp/test_smtp/
{
  "host": "127.0.0.1",
  "port": "25",
  "proto": "none",
  "user_email": "tester@example.org",
  "user": "tester",
  "password": "qwert12345",
  "timeout": 30000
}

Параметры запроса:

Название	Синтаксис	Обязательный	Описание
`host`	`<string>`	Да	Хост SMTP-сервера.
`port`	`<string>`	Да	Порт SMTP-сервера.
`proto`	`<string>`	Да	Протокол защиты соединения: `none`, `tls` или `ssl`.
`user_email`	`<string>`	Да	Адрес электронной почты.
`user`	`<string>`	Нет	Имя пользователя. Параметры `user` и `password` передаются только вместе.
`password`	`<string>`	Нет	Пароль пользователя SMTP. Параметры `user` и `password` передаются только вместе.
`timeout`	`<int>`	Нет	Время ожидания подключения и каждого ответа SMTP-сервера в миллисекундах.

Тайм-аут проверки

Если timeout не указан, используется значение 5000. Отрицательное значение отклоняется. При значении 0 или значении больше 300000 время ожидания каждой сетевой операции ограничивается 300 000 мс.

Неизвестные поля в теле запроса игнорируются.

Формат ответа

Ответ содержит следующие поля:

Поле	Синтаксис	Описание
`status`	`<string>`	Результат проверки: успех или причина сбоя.
`stage`	`<string>`	Стадия, на которой завершилась проверка.
`message`	`<string>`	Сообщение с результатом проверки.

Возможные значения status:

Значение	Описание
`success`	Проверка успешно завершена с аутентификацией.
`success_without_auth`	Проверка успешно завершена без аутентификации.
`invalid_configuration`	Параметры SMTP-конфигурации некорректны.
`connection_failed`	Не удалось подключиться к SMTP-серверу.
`secure_failed`	Не удалось установить защищенное соединение.
`authentication_not_supported`	SMTP-сервер не поддерживает аутентификацию.
`authentication_failed`	Ошибка аутентификации.
`sender_rejected`	SMTP-сервер отклонил адрес отправителя.
`timeout`	Превышено время ожидания.
`protocol_error`	Ошибка протокола SMTP.
`internal_error`	Внутренняя ошибка проверки.

Возможные значения stage:

Значение	Описание
`connect`	Подключение к SMTP-серверу.
`secure`	Установка защищенного соединения.
`greeting`	Получение приветствия SMTP-сервера.
`auth`	Аутентификация на SMTP-сервере.
`sender`	Проверка адреса отправителя командой `MAIL FROM`.

Для результатов invalid_configuration и internal_error поле stage отсутствует.

Код HTTP-ответа зависит от результата проверки:

Код	Значение `status`
`200`	Все значения, кроме `invalid_configuration` и `internal_error`.
`400`	`invalid_configuration`
`500`	`internal_error`

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

{
  "status": "success",
  "stage": "sender",
  "message": "SMTP configuration check completed successfully"
}

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

{
  "status": "connection_failed",
  "stage": "connect",
  "message": "Could not connect to the SMTP server"
}

Статистика заданий

Получение статистики выполнения задачи планировщика

GET _core/job_scheduler/statistic/{job_id}

Параметр	Тип	Описание
job_id	param	Идентификатор задания.
job_type	query	Тип задания (META, LOCAL).
size	query	Количество возвращаемых данных.
status	query	Статус возвращаемых элементов статистики (ошибка, предупреждение, норма).
earliest	query	Начало временного периода.
latest	query	Конец временного периода.

Получение статистики выполнения конкретного активного действия

GET _core/job_scheduler/statistic/{job_id}/{run_id}

Параметр	Тип	Описание
job_id	param	Идентификатор задания.
run_id	param	Идентификатор запуска.
job_type	query	Тип задания (META, LOCAL).
action	query	Тип активного действия.
number	query	Порядковый номер активного действия в списке действий задания.

Job​

Структура Job​

Throttle​

Schedule​

Cron​

Interval​

Search​

CRUD для Job​

Получение списка всех задач​

Получение задачи по ID​

Добавление новой задачи​

Обновление задачи​

Удаление задачи​

Запись в БД​

JDBC User​

Connection​

CRUD для JDBC User​

Получение списка всех пользователей​

Получение пользователя по ID​

Добавление нового пользователя​

Обновление пользователя​

Удаление пользователя​

Установка пароля пользователя​

CRUD для Connection​

Получение списка всех соединений​

Получение соединения по ID​

Добавление нового соединения​

Обновление соединения​

Удаление соединения​

Mail​

Recipient​

Recipient Group​

SMTP​

CRUD для Recipient​

Получение списка всех получателей​

Получение получателя по ID​

Добавление нового получателя​

Обновление получателя​

Удаление получателя​

CRUD для Recipient Group​

Получение списка всех групп получателей​

Получение группы получателей по ID​

Добавление новой группы получателей​

Обновление группы получателей​

Удаление группы получателей​

CRUD для SMTP​

Получение списка всех SMTP​

Получение SMTP по ID​

Добавление нового SMTP​

Обновление SMTP​

Удаление SMTP​

Проверка подключения к SMTP-серверу​

Проверка сохраненной SMTP-конфигурации​

Проверка SMTP-конфигурации по параметрам из тела запроса​

Формат ответа​

Статистика заданий​

Получение статистики выполнения задачи планировщика​

Получение статистики выполнения конкретного активного действия​

Job

Структура Job

Throttle

Schedule

Cron

Interval

Search

CRUD для Job

Получение списка всех задач

Получение задачи по ID

Добавление новой задачи

Обновление задачи

Удаление задачи

Запись в БД

JDBC User

Connection

CRUD для JDBC User

Получение списка всех пользователей

Получение пользователя по ID

Добавление нового пользователя

Обновление пользователя

Удаление пользователя

Установка пароля пользователя

CRUD для Connection

Получение списка всех соединений

Получение соединения по ID

Добавление нового соединения

Обновление соединения

Удаление соединения

Mail

Recipient

Recipient Group

SMTP

CRUD для Recipient

Получение списка всех получателей

Получение получателя по ID

Добавление нового получателя

Обновление получателя

Удаление получателя

CRUD для Recipient Group

Получение списка всех групп получателей

Получение группы получателей по ID

Добавление новой группы получателей

Обновление группы получателей

Удаление группы получателей

CRUD для SMTP

Получение списка всех SMTP

Получение SMTP по ID

Добавление нового SMTP

Обновление SMTP

Удаление SMTP

Проверка подключения к SMTP-серверу

Проверка сохраненной SMTP-конфигурации

Проверка SMTP-конфигурации по параметрам из тела запроса

Формат ответа

Статистика заданий

Получение статистики выполнения задачи планировщика

Получение статистики выполнения конкретного активного действия