Плейбуки

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

О плейбуках

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

Работа с плейбуком

Доступные операции над плейбуком:

Создание плейбука
Запуск плейбука
Изменение плейбука
Удаление плейбука

Создание плейбука

Плейбук можно создать самостоятельно или импортировать в систему.

Чтобы создать плейбук:

Перейдите в раздел Экспертиза. Система отобразит список элементов экспертизы.
На панели инструментов нажмите на кнопку Создать и выберите из выпадающего списка пункт Плейбук.
Создайте плейбук, определив логику его работы.

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

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

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

Запуск плейбука

После того как плейбук протестирован и сохранен, он готов к запуску.

Чтобы запустить плейбук:

Перейдите в раздел Экспертиза. Система отобразит список элементов экспертизы.
Нажмите на строку плейбука в списке. Система отобразит в правой части экрана карточку этого плейбука с подробной информацией о нем.
Убедитесь, что плейбук включен. Переключатель в карточке плейбука должен быть переведен в активное положение.
Нажмите на кнопку Запустить в карточке плейбука. Плейбук будет запущен.

Плейбук можно также запустить из раздела Запуски.

Процесс выполнения плейбука в системе

Если у плейбука есть аргументы, после запуска плейбука отображается окно для ввода аргументов. Типы аргументов совпадают с типами переменных и зависят от языка плейбука.
После задания аргументов система преобразует их в формат JSON и передает плейбук на выполнение в воркер. При запуске плейбука система назначает ему специальный тег воркера. Нельзя смешивать этот тег с тегами, используемыми в Экспертизе для группировки плейбуков по бизнес-модели. Тег воркера, назначаемый плейбуку системой, указывает, какой конкретный воркер будет выполнять этот плейбук.

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

Плейбук может включать различные виды модулей.
Для каждого отдельного модуля плейбука воркер создает отдельную задачу и выполняет следующие шаги:
1. Если необходимо отдельно установить определенные зависимости модуля, воркер производит установку зависимостей в рамках отдельной задачи. Установленные зависимости в дальнейшем хранятся на этом воркере. Они используются при последующих выполнениях модуля на этом воркере, что сокращает время работы.
2. После проверки наличия и установки зависимостей воркер проверяет, запускался ли этот модуль ранее с такими же параметрами и сохранились ли результаты этого запуска в кэше.
  
  Если такие данные сохранены в кэше, воркер предоставит их, что ускорит выполнение процесса.
  
  Пример
  
  Модуль производит следующую трансформацию входных данных в выходные данные — принимает объемные входные данные, преобразует их в JSON-файл, ищет определенное поле и передает его на выход. Если такой модуль с такими параметрами уже ранее запускался, воркер попытается найти кэшированные данные и предоставить их, не тратя времени на запуск скрипта.
3. Если готовый результат не найден, задача передается на выполнение. Каждый воркер в отдельный момент времени выполняет только одну задачу.
4. Воркер запускает процесс с интерпретатором требуемого языка. В файловой системе в отдельной директории сохраняются все необходимые данные. Например, аргументы, ссылки на зависимости, необходимые для запуска и указанные пользователем переменные окружения.
5. Система помещает модуль в специальную оболочку, позволяющую через библиотеку playbooks_sdk бесшовно получать доступ к переменным, элементам экспертизы, запускам и интеграциям с другими сервисами.
6. Модуль выполняется.
После выполнения всех модулей воркер завершает процесс, кэширует результаты и удаляет директорию с артефактами работы, так как все необходимые данные уже сохранены. После этого воркер переходит в режим ожидания следующей задачи.

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

Изменение плейбука

Чтобы изменить плейбук:

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

Нажмите на кнопку действий ( more vertical ) в верхнем правом углу карточки и выберите опцию Изменить. Отобразится окно настроек плейбука.

Вы также можете открыть окно настроек с помощью кнопки в нижней части карточки:

Для опубликованной версии: нажмите на кнопку Просмотр в нижней части карточки. Система отобразит окно просмотра настроек элемента экспертизы. Нажмите на кнопку Изменить в правом нижнем углу окна.
Для черновика: нажмите на кнопку Изменить в нижней части карточки.

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

При публикации новой версии элемента экспертизы требуется увеличить его текущую версию в поле version.

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

Удаление плейбука

Чтобы удалить плейбук:

Перейдите в раздел Экспертиза. Система отобразит сведения об имеющихся элементах экспертизы.
Нажмите на строку плейбука в списке. Система отобразит в правой части экрана карточку с подробной информацией о плейбуке.
Нажмите на кнопку действий () в верхнем правом углу карточки и выберите опцию Удалить. Отобразится окно подтверждения удаления плейбука.
Нажмите на кнопку Удалить. Система удалит плейбук и отобразит соответствующее уведомление. Удаленный плейбук будет исключен из списка элементов экспертизы.

Вы также можете удалить группу элементов экспертизы. Для этого:

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

Структура RObject-схемы плейбука

Описание плейбука начинается с блока метаданных плейбука.

Содержимое плейбука находится в поле body — входные аргументы в поле input и модули в поле modules.

Блок настроек выполнения плейбука является необязательным.

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

Поля метаданных

Запись метаданных включает следующие обязательные поля:

Поле Описание Тип данных

Поле	Описание	Тип данных
`id`	Уникальный идентификатор плейбука	строка
`type`	Тип элемента экспертизы. Для плейбука здесь всегда устанавливается значение `playbook`.
`name`	Название. Допустимы строчные и прописные буквы латинского алфавита (`a—z`, `A—Z`), цифры (`0—9`), точка, подчеркивание и дефис без пробелов.	строка
`version`	Версия плейбука в формате Semantic Versioning.	строка

id

Уникальный идентификатор плейбука

строка

type

Тип элемента экспертизы. Для плейбука здесь всегда устанавливается значение playbook.

name

Название.

Допустимы строчные и прописные буквы латинского алфавита (a—z, A—Z), цифры (0—9), точка, подчеркивание и дефис без пробелов.

строка

version

Версия плейбука в формате Semantic Versioning.

строка

Вы также можете добавить в метаданные любые другие поля, содержащие дополнительные сведения о плейбуке (например, поле author).

Поле `input`

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

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

Поле Описание Тип данных

Поле	Описание	Тип данных
`properties`	Массив записей с описанием входных аргументов	массив

properties

Массив записей с описанием входных аргументов

массив

Поле `properties`

Структура поля properties включает описание полей входных аргументов:

Поле Описание Тип данных

Поле	Описание	Тип данных
`type`	Тип поля	строка, число
`default`	Значение в поле, отображаемое по умолчанию	зависит от типа поля
`description`	Описание поля (отображается рядом с полем)	строка
`required`	Поле обязательно для заполнения. Значение обязательно должно быть передано.	логическое

type

Тип поля

строка, число

default

Значение в поле, отображаемое по умолчанию

зависит от типа поля

description

Описание поля (отображается рядом с полем)

строка

required

Поле обязательно для заполнения. Значение обязательно должно быть передано.

логическое

Поле `modules`

Поле modules содержит массив модулей. Общая структура каждого модуля включает следующие поля:

Поле Описание Тип данных Обязательное поле

Поле	Описание	Тип данных	Обязательное поле
`id`	Идентификатор модуля	строка	да
`body`	Описание всех модулей, включенных в этот модуль, в заданной последовательности выполнения. Модуль может включать любое количество модулей разных типов. Поля модулей подробно описаны в статье Модули плейбуков.	массив	да
`failure_module`	Описание модуля сбоя, запускаемого в случае ошибки при выполнении модулей, описанных в поле `body`. Если в поле не задано описание модуля `failure_module`, в случае ошибки при выполнении модулей плейбука будет возвращено сообщение об ошибке. Модуль `failure_module` имеет такую же структуру, как и другие модули, задаваемые в плейбуках.	массив	нет
`summary`	Описание модуля. Может содержать необходимую пользователю информацию о работе и назначении модуля.	строка	нет
`sleep_secs`	Время ожидания перед началом выполнения модуля в секундах. Может использоваться, если по результатам выполнения предыдущего модуля система должна выполнить определенные действия (например, обновления). Позволяет задать время ожидания этого выполнения. См. описание поля.	массив	нет
`continue_on_error`	Продолжение выполнения модуля при ошибке. Позволяет определить, будет ли продолжено выполнение модуля при возникновении ошибки. Доступные значения: `true` — продолжить выполнение модуля при ошибке; `false` — остановить выполнение модуля.	логическое	нет
`retry`	Повторы выполнения модуля при его неуспешном выполнении. Позволяет настроить жестко или гибко заданное количество повторов выполнения модуля.	массив	нет
`priority`	Приоритетность выполнения модуля. В зависимости от важности задачи, выполняемой модулем, можно определить его приоритетность по сравнению с обработкой других элементов экспертизы. Возможные значения: от `1` (минимальная приоритетность) до `100` (максимальная приоритетность).	целое число	нет
`mock`	Отмена выполнения модуля. Может использоваться при отладке плейбука. Если в поле указано значение, оно будет возвращено вместо фактического выполнения модуля. См. описание поля.	строка	нет
`suspend`	Действие, выполнение которого должно предшествовать запуску модуля.		нет
`cache_ttl`	Время жизни (TTL, time to live) кэша данных скрипта в секундах. Может использоваться при работе модуля с внешним объектом (например, активными списками), чтобы соотносить время жизни кэша данных модуля и объекта. Параметр позволяет не хранить данные в кэше модуля дольше, чем они хранятся в кэше объекта. Время хранения определяется этим параметром. Если время жизни кэша данных модуля не указано в самой задаче, система берет его значение из этого поля.	целое число	нет
`timeout`	Максимальное время выполнения модуля в секундах. Если время выполнения модуля превышает максимальное, модуль будет принудительно остановлен с ошибкой выполнения.	целое число	нет
`delete_after_use`	Удаление значения, возвращаемого модулем после выполнения. Возможные значения: `true` — значение, возвращаемое модулем, будет удалено; `false` — значение, возвращаемое модулем, будет сохранено.	логическое	нет
`stop_after_if`	Остановка выполнения всех последующих модулей, если выражение, заданное в поле, возвращает значение `true`. См. описание поля.	логическое	нет

id

Идентификатор модуля

строка

да

body

Описание всех модулей, включенных в этот модуль, в заданной последовательности выполнения.

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

массив

да

failure_module

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

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

Модуль failure_module имеет такую же структуру, как и другие модули, задаваемые в плейбуках.

массив

нет

summary

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

строка

нет

sleep_secs

Время ожидания перед началом выполнения модуля в секундах.

Может использоваться, если по результатам выполнения предыдущего модуля система должна выполнить определенные действия (например, обновления). Позволяет задать время ожидания этого выполнения. См. описание поля.

массив

нет

continue_on_error

Продолжение выполнения модуля при ошибке. Позволяет определить, будет ли продолжено выполнение модуля при возникновении ошибки. Доступные значения:

true — продолжить выполнение модуля при ошибке;
false — остановить выполнение модуля.

логическое

нет

retry

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

массив

нет

priority

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

Возможные значения: от 1 (минимальная приоритетность) до 100 (максимальная приоритетность).

целое число

нет

mock

Отмена выполнения модуля.

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

строка

нет

suspend

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

нет

cache_ttl

Время жизни (TTL, time to live) кэша данных скрипта в секундах.

Может использоваться при работе модуля с внешним объектом (например, активными списками), чтобы соотносить время жизни кэша данных модуля и объекта. Параметр позволяет не хранить данные в кэше модуля дольше, чем они хранятся в кэше объекта.

Время хранения определяется этим параметром. Если время жизни кэша данных модуля не указано в самой задаче, система берет его значение из этого поля.

целое число

нет

timeout

Максимальное время выполнения модуля в секундах.

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

целое число

нет

delete_after_use

Удаление значения, возвращаемого модулем после выполнения.

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

true — значение, возвращаемое модулем, будет удалено;
false — значение, возвращаемое модулем, будет сохранено.

логическое

нет

stop_after_if

Остановка выполнения всех последующих модулей, если выражение, заданное в поле, возвращает значение true. См. описание поля.

логическое

нет

Поле `sleep_secs`

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

Поле Описание

Поле	Описание
`type`	Формат времени ожидания. Может иметь одно из следующих значений: `static` — статический формат; `js` — формат выражения на языке JavaScript.
`value`	Значение времени ожидания. Если выбран тип `static`, необходимо задать количество секунд ожидания: `value: <целое число>`. Если выбран тип `js`, необходимо задать выражение на языке JavaScript. После выполнения выражение возвращает количество секунд ожидания: `value: <выражение на языке JavaScript>`.

type

Формат времени ожидания.

Может иметь одно из следующих значений:

static — статический формат;
js — формат выражения на языке JavaScript.

value

Значение времени ожидания.

Если выбран тип static, необходимо задать количество секунд ожидания: value: <целое число>.
Если выбран тип js, необходимо задать выражение на языке JavaScript. После выполнения выражение возвращает количество секунд ожидания: value: <выражение на языке JavaScript>.

Пример настройки в статическом формате, задающей 10-секундное ожидание перед началом выполнения модуля.

# Настройка времени ожидания перед началом выполнения модуля
sleep_secs:
    # Статический формат
    type: static
    # Количество секунд ожидания
    value: 10

Пример настройки в формате выражения JavaScript. Указанное выражение возвращает время ожидания перед началом выполнения плейбука.

 # Настройка времени ожидания перед началом выполнения модуля.
 sleep_secs:
     # Формат выражения JS.
     type: js
     # Выражение JS.
     value: flow_input.sleep + 100

Поле `retry`

Структура поля retry включает поля constant и exponential, определяющие условия повтора выполнения модуля в различных форматах.

Можно определить одно или оба условия. Если определены оба условия, сначала будет выполнено условие, заданное в поле constant.

Поле Описание Тип данных

Поле	Описание	Тип данных
`constant`	Жестко заданный формат. Может использоваться, если внешние сервисы, к которым обращается модуль, доступны, но могут иногда возвращать ошибки в ответ на запросы. В таких случаях лучше задавать настройку повторных запросов через определенный фиксированный интервал. Если выбран этот формат, необходимо заполнить следующие поля: `attempts` — количество повторных попыток выполнения модуля; `delay_secs` — интервал между попытками выполнения в секундах.	массив
`exponential`	Экспоненциальный формат. Может использоваться, если внешние сервисы, к которым обращается модуль, зависят от сетевого соединения. В таких случаях лучше выполнять повторные запросы через постоянно увеличивающийся интервал времени, ожидая появления сервиса в сети. Если выбран этот формат, необходимо заполнить следующие поля: `attempts` — количество повторных попыток выполнения модуля; `multiplier` — множитель, определяющий фактический интервал между попытками выполнения; `delay_secs` — базовый интервал между попытками выполнения в секундах.	целое число или выражение

constant

Жестко заданный формат.

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

Если выбран этот формат, необходимо заполнить следующие поля:

attempts — количество повторных попыток выполнения модуля;
delay_secs — интервал между попытками выполнения в секундах.

массив

exponential

Экспоненциальный формат.

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

Если выбран этот формат, необходимо заполнить следующие поля:

attempts — количество повторных попыток выполнения модуля;
multiplier — множитель, определяющий фактический интервал между попытками выполнения;
delay_secs — базовый интервал между попытками выполнения в секундах.

целое число или выражение

Пример настройки в жестко заданном формате

Настройка задает 45 попыток повторного запуска и 67-секундный интервал между попытками повторного запуска.

# Настройка повторов выполнения модуля при его неуспешном выполнении.
retry:
  # Жестко заданный формат.
  constant:
     # Количество попыток повторного запуска
     attempts: 45
     # Интервал между попытками
     delay_secs: 67

Пример настройки в экспоненциальном формате

Согласно этой настройке первая повторная попытка будет выполнена через 4 сек., вторая — через 12 сек. (4*3), а третья — через 36 сек. (12*3).

# Настройка повторов выполнения модуля при его неуспешном выполнении
retry:
   # Экспоненциальный формат
   exponential
      # Количество попыток повторного запуска.
      attempts: 3
      # Множитель, определяющий фактический интервал между попытками выполнения.
      multiplier: 3
      # Базовый интервал между попытками выполнения (сек.).
      delay_secs: 4

Поле `mock`

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

Поле Описание

Поле	Описание
`new_value`	Поле для указания значения, которое будет возвращено системой вместо фактического выполнения модуля

new_value

Поле для указания значения, которое будет возвращено системой вместо фактического выполнения модуля

Пример настройки

Согласно этой настройке вместо выполнения модуля будет возвращено значение 1.

# Настройка, позволяющая отменить выполнение модуля.
mock:
    # Если указано это поле, модуль вернет указанное значение вместо выполнения.
    new_value: 1

Поле `stop_after_if`

Структура поля stop_after_if включает действия, определяющие, будет ли плейбук выполняться дальше.

Необходимо выбрать одно из действий.

Поле Описание Тип данных

Поле	Описание	Тип данных
`expr`	Выражение возвращает значение, определяющее, будет ли остановлено выполнение процесса (цикла или плейбука). Возможные значения: Если поле используется в цикле: `true` — выполнение цикла будет остановлено; `false` — выполнение цикла не будет остановлено. Если поле используется в модуле, который не является циклом: `true` — выполнение плейбука будет остановлено; `false` — выполнение плейбука не будет остановлено.	логическое
`skip_if_stopped`	Позволяет пометить остановленный плейбук как пропущенный. Возможные значения: `true` — остановленный плейбук или цикл будет помечен как пропущенный; `false` — остановленный плейбук или цикл будет помечен как выполненный.	логическое

expr

Выражение возвращает значение, определяющее, будет ли остановлено выполнение процесса (цикла или плейбука).

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

Если поле используется в цикле:
- true — выполнение цикла будет остановлено;
- false — выполнение цикла не будет остановлено.
Если поле используется в модуле, который не является циклом:
- true — выполнение плейбука будет остановлено;
- false — выполнение плейбука не будет остановлено.

логическое

skip_if_stopped

Позволяет пометить остановленный плейбук как пропущенный.

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

true — остановленный плейбук или цикл будет помечен как пропущенный;
false — остановленный плейбук или цикл будет помечен как выполненный.

логическое

Блок настроек выполнения плейбука

Блок включает следующие поля:

Поле Описание Тип данных

Поле	Описание	Тип данных
`same_worker`	Необходимость выполнения родительского плейбука и текущего плейбука на одном и том же воркере. Используется, если текущий плейбук запускается в ходе выполнения определенного (родительского) плейбука. Если в родительском плейбуке не заполнено поле `same_worker`, именно это поле будет определять, выполнится ли текущий плейбук на том же воркере, что и родительский. Возможные значения: `true` — оба плейбука выполняются на одном и том же воркере; `false` — текущий и родительский плейбуки могут выполняться на разных воркерах.	булево
`concurrent_limit`	Количество параллельных выполнений плейбука. Используется, если для корректной работы плейбука необходимо ввести это ограничение. Например, у сервера, к которому обращается задача при выполнении плейбука, может быть ограниченное количество входных соединений. Этот параметр позволяет ограничить количество выполняющихся экземпляров плейбука количеством входных соединений. В результате будет установлено разрешенное количество соединений для выполнений плейбука, а лимит превышен не будет.	целое число
`concurrency_time_window_t`	Максимально допустимое время выполнения задачи в секундах при параллельном выполнении. Если оно превысит значение, указанное в этом поле, задача будет отменена.	целое число
`skip_expr`	Необходимость выполнения плейбука по результатам проверки определенного условия. Выражение на языке JavaScript. Выполняется до запуска плейбука, проверяет определенные условия и по результатам проверки определяет необходимость его запуска. Пример. В ходе выполнения плейбука предполагается его обращение к определенному сервису. Выражение может проверить доступность порта сервиса через утилиту `ping`. Если порт недоступен, плейбук выполнен не будет. Возвращаемое значение выражения: `true` — плейбук не будет выполнен; `false` — плейбук будет выполнен.	строка
`cache_ttl`	Время жизни (TTL, time to live) кэша данных плейбука в секундах. Параметр можно использовать при работе плейбука с внешним объектом (например, активными списками). Он позволяет не хранить данные в кэше плейбука дольше, чем они хранятся в кэше объекта. Время хранения кэша данных плейбука определяется этим параметром.	целое число
`early_return`	Необходимость повторного запуска плейбука в случае ошибки. Возможные значения: `true` — в случае сбоя выполнения плейбука система не пытается запустить плейбук повторно; `false` — в случае сбоя выполнения плейбука система предпринимает попытку повторного запуска.	логическое
`priority`	Приоритетность выполнения плейбука. В зависимости от важности задачи, выполняемой плейбуком, можно определить его приоритетность по сравнению с обработкой других элементов экспертизы. Возможные значения: от `1` (минимальная приоритетность) до `100` (максимальная приоритетность).	целое число

same_worker

Необходимость выполнения родительского плейбука и текущего плейбука на одном и том же воркере.

Используется, если текущий плейбук запускается в ходе выполнения определенного (родительского) плейбука. Если в родительском плейбуке не заполнено поле same_worker, именно это поле будет определять, выполнится ли текущий плейбук на том же воркере, что и родительский.

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

true — оба плейбука выполняются на одном и том же воркере;
false — текущий и родительский плейбуки могут выполняться на разных воркерах.

булево

concurrent_limit

Количество параллельных выполнений плейбука.

Используется, если для корректной работы плейбука необходимо ввести это ограничение. Например, у сервера, к которому обращается задача при выполнении плейбука, может быть ограниченное количество входных соединений. Этот параметр позволяет ограничить количество выполняющихся экземпляров плейбука количеством входных соединений. В результате будет установлено разрешенное количество соединений для выполнений плейбука, а лимит превышен не будет.

целое число

concurrency_time_window_t

Максимально допустимое время выполнения задачи в секундах при параллельном выполнении. Если оно превысит значение, указанное в этом поле, задача будет отменена.

целое число

skip_expr

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

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

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

Возвращаемое значение выражения:

true — плейбук не будет выполнен;
false — плейбук будет выполнен.

строка

cache_ttl

Время жизни (TTL, time to live) кэша данных плейбука в секундах.

Параметр можно использовать при работе плейбука с внешним объектом (например, активными списками). Он позволяет не хранить данные в кэше плейбука дольше, чем они хранятся в кэше объекта. Время хранения кэша данных плейбука определяется этим параметром.

целое число

early_return

Необходимость повторного запуска плейбука в случае ошибки.

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

true — в случае сбоя выполнения плейбука система не пытается запустить плейбук повторно;
false — в случае сбоя выполнения плейбука система предпринимает попытку повторного запуска.

логическое

priority

Приоритетность выполнения плейбука.

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

Возможные значения: от 1 (минимальная приоритетность) до 100 (максимальная приоритетность).

целое число

Составление плейбука

Для создания плейбука:

Опишите метаданные плейбука (id, type, name, version).
Пример заполненной структуры метаданных
id: playbook_new_version type: playbook name: playbook_new_version_name version: 1.0.0

Опишите содержимое плейбука в поле body:

Опишите блок входных аргументов в поле input.

Пример записей в поле input

input:
    # Блок, в котором перечисляются входные аргументы.
    properties:
       # Первый входной аргумент.
       employeename:
            # Тип первого входного аргумента.
            type: string
            # Описание первого входного аргумента.
            description: "Employee first name"
            # Значение первого входного аргумента по умолчанию.
            default: "default_employeename"
            # Аргумент является обяязательным.
            required: true
       # Второй входной аргумент.
       age:
            type: number
            default: 35
            description: "Age description"

Опишите в поле modules модули требуемых типов. При запуске плейбука все описанные модули выполняются последовательно.

Структура поля modules плейбука:

modules:
    # Идентификатор первого модуля плейбука.
    - id:
      # Поле, содержащее описание первого модуля (скрипты, плейбуки, циклы со своими модулями и т.д.).
      body:
        # Тип первого модуля.
        type:
        # Под полем type располагаются записи полей, описывающие модуль выбранного типа. Набоор полей зависит от типа модуля.

    # Идентификатор второго модуля плейбука.
    - id:
    # Поле, содержащее описание второго модуля.
    body:
       # Тип второго модуля
       type:
    # И так далее.
    ...

Добавьте описание модуля сбоя failure_module для плейбука (опционально).
Модуль сбоя имеет такую же структуру, что и другие модули.
Добавьте блок настроек выполнения плейбука (опционально).

Пример плейбука

id: playbook_with_rawscript
name: Playbook with rawscript
description: Плейбук с модулем rawscript
version: 0.0.1
type: playbook
body:
  input:
    properties:
      name_string:
        type: string
        description: ""
        default: "1se"
  modules:
      - id: rawscript_module_x
        body:
          type: rawscript
          input:
            x: # Значение аргумента берется из name_string
              type: js
              expr: playbook_input.name_string
          source: !py |
            def main(x: str):
              new_text = 'Текст для вывода ' + x
              return(new_text)
          retry:
            constant:
              attempts: 2
              delay_secs: 5
      - id: rawscript_module_y
        body:
          type: rawscript
          input:
            y: # Значение аргумента берется из name_string
              type: js
              expr: playbook_input.name_string
          source: !bun |
            function main(y: string): void {
              const newText = 'Текст для вывода ' + y;
              console.log(newText);
            }
          retry:
            constant:
              attempts: 2
              delay_secs: 5

Особенности работы с модулями

Цикл

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

Ветвления

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

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

Повторы запуска модулей и обработка ошибок

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

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

Доступ к хранилищу данных

Когда плейбук запускается, система создает в специальном хранилище данных запись о запуске. Эти записи можно использовать в плейбуках, например, как условие срабатывания определенного правила. Каждая запись в хранилище имеет свой идентификатор (ID интеграции), на который пользователь может ссылаться в плейбуках.

Плейбуки

О плейбуках

Работа с плейбуком

Создание плейбука

Запуск плейбука

Процесс выполнения плейбука в системе

Изменение плейбука

Удаление плейбука

Структура RObject-схемы плейбука

Поля метаданных

Поле input

Поле properties

Поле modules

Поле sleep_secs

Поле retry

Поле mock

Поле stop_after_if

Блок настроек выполнения плейбука

Составление плейбука

Пример плейбука

Особенности работы с модулями

Цикл

Ветвления

Повторы запуска модулей и обработка ошибок

Доступ к хранилищу данных

Поле `input`

Поле `properties`

Поле `modules`

Поле `sleep_secs`

Поле `retry`

Поле `mock`

Поле `stop_after_if`