Engine
Движок сценариев: запуск и остановка, задачи, потоки, переменные, ресурсы и функции.
Engine.api.engine управляет выполнением: запускает и останавливает сценарий, создаёт задачи и потоки, читает и пишет переменные и ресурсы, вызывает функции. Все методы асинхронные — вызывайте их через await и проверяйте success.
ℹ️ Перед обращением к движку убедитесь, что связь установлена: дождитесь события
engine:connectedили вызовитеEngine.api.engine.whenConnected(). См. Начало работы.
Общие понятия
- Сценарий запускается в один или несколько потоков. Потоки выполняют один и тот же сценарий параллельно.
- Задача — независимый параллельный процесс со своим изолированным контекстом (переменные, ресурсы). Остановка сценария не затрагивает задачи, и сбой в одной задаче не влияет на другие.
- Функция — блок действий сценария. Точка входа —
Main. Функцию можно вызвать отдельно. - Аргументы запуска передаются в точку входа как локальные переменные — внутри сценария они доступны как
[[имя]]. - Значения ресурсов можно переопределить при запуске, не меняя сам сценарий.
Управление сценарием
Запустить сценарий
Engine.api.engine.startScenario(количествоПотоков, параметры?) — запускает основной сценарий в указанном числе потоков.
Параметры:
количествоПотоков(число) — сколько параллельных потоков создать.параметры(объект, необязательно):function_name— с какой функции стартовать (по умолчаниюMain);arguments— объект значений, передаваемых в точку входа как переменные;resources_values— объект переопределений значений ресурсов;thread_names— массив имён потоков;max_success— остановиться после стольких успешных завершений;max_failed— остановиться после стольких ошибок;label— метка запуска для отображения.
Возвращает: признак запуска и сведения о созданных потоках.
await Engine.api.engine.whenConnected();
const res = await Engine.api.engine.startScenario(5, {
arguments: { mode: 'fast' },
resources_values: { apiUrl: 'https://api.example.com' },
max_failed: 10
});
if (res.success) console.log('Сценарий запущен');Остановить сценарий
Engine.api.engine.stopScenario(идентификатор?) — останавливает выполняющийся сценарий. Идентификатор можно не указывать — будет остановлен текущий.
Приостановить и возобновить сценарий
Engine.api.engine.pauseScenario(идентификатор?) и Engine.api.engine.resumeScenario(идентификатор?) — приостанавливают и возобновляют сценарий. На паузе потоки замирают между действиями.
Узнать статус сценария
Engine.api.engine.getScenarioStatus(идентификатор?) — возвращает текущий статус сценария: работает ли он, сколько потоков активно, на каком шаге они находятся.
const res = await Engine.api.engine.getScenarioStatus();
if (res.success) {
console.log('Сценарий работает:', res.data.running);
}Задачи
Задачи удобны, когда рядом с основным сценарием нужно запустить независимый фоновый процесс.
Запустить задачу
Engine.api.engine.startTask(имяФункции, параметры?) — запускает независимую задачу. Возвращает управление сразу — задача работает в фоне, пока не достигнет ограничений.
Параметры:
имяФункции— функция, с которой стартует каждый рабочий поток задачи.параметры(объект, необязательно):max_threads— число потоков задачи;arguments— переменные точки входа;resources_values— переопределения ресурсов;max_success,max_failed— ограничения;label— метка.
Возвращает: идентификатор задачи (task_id) для дальнейшего управления.
const res = await Engine.api.engine.startTask('ProcessQueue', {
max_threads: 3,
label: 'Обработка очереди'
});
const taskId = res.data.task_id;Остановить задачу
Engine.api.engine.stopTask(идентификаторЗадачи) — останавливает задачу.
Приостановить и возобновить задачу
Engine.api.engine.pauseTask(идентификаторЗадачи) и Engine.api.engine.resumeTask(идентификаторЗадачи) — приостанавливают и возобновляют задачу, не затрагивая остальные.
Узнать состояние задачи
Engine.api.engine.getTaskInfo(идентификаторЗадачи, параметры?) — возвращает состояние задачи: время работы, статистику, сводку логов. Через параметры можно указать, что включать в ответ (статистику, логи, историю) — для частых опросов запрашивайте минимум.
const res = await Engine.api.engine.getTaskInfo(taskId, { include_statistics: true });
console.log(res.data);Список задач и сценариев
Engine.api.engine.getAvailableTasks(вид?) — возвращает список всех задач и сценариев с их статусом. вид — необязательный фильтр: 'task' или 'scenario'.
const res = await Engine.api.engine.getAvailableTasks('task');
console.log('Задач:', res.data);Потоки
Потоки нужны для тонкого управления параллельным выполнением.
Запустить поток
Engine.api.engine.startThread(имяФункции, параметры?) — запускает функцию один раз в отдельном изолированном потоке. Поток завершается после выполнения функции.
Параметры: имяФункции — точка входа (по умолчанию Main); параметры — resources_values, thread_name, label.
const res = await Engine.api.engine.startThread('SendReport', {
thread_name: 'Отчёт'
});Остановить поток
Engine.api.engine.stopThread(идентификаторПотока) — останавливает поток.
Список потоков
Engine.api.engine.getThreads(статус?) — возвращает список потоков. статус — необязательный фильтр (например, 'running').
Сведения о потоке
Engine.api.engine.getThreadInfo(идентификаторПотока) — возвращает сведения о потоке и снимок его состояния: переменные, ресурсы, стек вызовов.
Состояние потока
Engine.api.engine.getThreadState(идентификаторПотока?) — возвращает состояние потока. Если идентификатор не указан — состояние потока текущего интерфейса.
Создать поток для интерфейса
Engine.api.engine.createInterfaceThread(имя?) — создаёт для интерфейса собственный поток. Обычно интерфейс делает это автоматически при подключении — вручную нужно лишь в особых случаях.
Вызов функций
Выполнить функцию сценария
Engine.api.engine.executeFunction(имяФункции, аргументы?, асинхронно?, имяРезультата?, областьРезультата?) — выполняет функцию сценария.
Параметры:
имяФункции— какую функцию выполнить;аргументы(объект) — значения, передаваемые в функцию;асинхронно(булево) — еслиtrue, функция запускается в фоне, а метод возвращает управление сразу;имяРезультата— имя переменной, в которую сохранить возвращаемое значение функции;областьРезультата— область этой переменной:'local'или'global'.
Возвращает: при синхронном вызове — результат выполнения функции; при асинхронном — идентификатор запущенного выполнения.
// Синхронно: ждём результат
const res = await Engine.api.engine.executeFunction('CalcTotal', { items: 5 });
if (res.success) console.log('Итог:', res.data.result);
// Асинхронно: запускаем в фоне
await Engine.api.engine.executeFunction('LongJob', {}, true);Отменить асинхронное выполнение
Engine.api.engine.stopExecution(идентификаторВыполнения) — отменяет запущенное асинхронное выполнение функции.
Список выполнений функций
Engine.api.engine.getExecutions(статус?) — возвращает список выполнений функций (запущенные, завершённые, отменённые). статус — необязательный фильтр.
Список функций сценария
Engine.api.engine.getFunctions() — возвращает список функций сценария с их описанием: параметры, возвращает ли функция значение, число действий.
Сведения об одной функции
Engine.api.engine.getFunctionInfo(имяФункции) — возвращает подробную информацию об одной функции.
Переменные
Методы работают с контекстом потока текущего интерфейса. Переменные бывают локальными (в пределах потока) и глобальными (общими для всех потоков).
Прочитать переменную
Engine.api.engine.getVariable(имя) — возвращает значение переменной. Поиск идёт сначала среди локальных, затем среди глобальных.
const res = await Engine.api.engine.getVariable('counter');
if (res.success) console.log(res.data.value);Записать локальную переменную
Engine.api.engine.setVariable(имя, значение, тип?) — устанавливает локальную переменную. тип — необязательно ('string', 'number', 'boolean', 'object', 'array'); обычно определяется автоматически.
await Engine.api.engine.setVariable('counter', 42, 'number');Прочитать и записать глобальную переменную
Engine.api.engine.getGlobalVariable(имя) и Engine.api.engine.setGlobalVariable(имя, значение, тип?) — читают и записывают глобальную переменную, общую для всех потоков.
await Engine.api.engine.setGlobalVariable('apiUrl', 'https://api.example.com');Удалить переменную
Engine.api.engine.deleteVariable(имя, область?) — удаляет переменную. область — 'local' (по умолчанию) или 'global'.
Получить все переменные потока
Engine.api.engine.getAllVariables() — возвращает все переменные потока: объединённое представление локальных и глобальных.
const res = await Engine.api.engine.getAllVariables();
console.log(res.data.variables);⚠️ Некоторые переменные помечены как защищённые — их нельзя изменить или удалить. Попытка вернёт ошибку в
error.
Ресурсы сценария
В отличие от ресурсов интерфейса, эти методы обращаются к значениям ресурсов внутри контекста выполняющегося сценария.
Прочитать ресурс сценария
Engine.api.engine.getResource(идентификатор) — возвращает значение ресурса из контекста сценария.
Записать ресурс сценария
Engine.api.engine.setResource(идентификатор, значение) — устанавливает значение ресурса в контексте сценария.
Получить все ресурсы сценария
Engine.api.engine.getAllResources() — возвращает все ресурсы контекста сценария.
Состояние движка
Дождаться связи с движком
Engine.api.engine.whenConnected(таймаут?) — возвращает Promise, который разрешается, как только установлена связь с движком. Если связь уже есть — разрешается сразу. таймаут — время ожидания в миллисекундах (по умолчанию 15000; 0 — ждать бесконечно).
await Engine.api.engine.whenConnected();Проверить состояние подключения
Engine.api.engine.getStatus() — возвращает состояние подключения интерфейса к движку: инициализирован ли, есть ли связь, идентификаторы сценария и потока.
const res = Engine.api.engine.getStatus();
console.log('Связь с движком:', res.data.connected);Подключиться и отключиться вручную
Engine.api.engine.connect() и Engine.api.engine.disconnect() — устанавливают или разрывают связь с движком вручную. Обычно подключение происходит автоматически при запуске интерфейса.