Модули плейбуков

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

Содержание полей зависит от типа модуля. В системе существуют следующие типы модулей:

Специальные переменные

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

Тип script

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

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

type

Тип модуля. Устанавливается значение script.

строка

id

Ссылка на идентификатор существующего скрипта, который будет выполняться на этом шаге плейбука

строка

input

Входные аргументы

массив

tag_override

Переопределение тега скрипта.

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

строка

Пример описания модуля типа script в поле modules в схеме плейбука:
modules:
    # Идентификатор модуля
    - id: "1_module_id"
      Группа полей, описывающая скрипт
      body:
        # Тип модуля - скрипт
        type: script
        # Идентификатор скрипта
        id: 84895c89-468e-41f8-9f52-ad854d36734f
        # Входные аргументы скрипта
        input:
            age:
                type: static
                expr: 'arg_value'
            name:
                type: js
                expr: flow_input.filename
        # Переопределение тега скрипта
        tag_override: 'worker_456'

Тип playbook

Описание плейбука включает следующие поля:

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

type

Тип модуля. Устанавливается значение playbook.

строка

input

Входные аргументы

массив

Пример описания модуля типа playbook в поле modules в схеме плейбука:
modules:
    # Идентификатор модуля
    - id: "2_module_id"
      # Группа полей, описывающая плейбук
      body:
        # Тип модуля - playbook
        type: playbook
        id: 893495c89-434e-49s8
        # Входные аргументы плейбука
        input:
           age:
                type: js
                expr: flow_input_age
            name:
                type: js
                expr: flow_input.filename

Тип forloop

Описание типа модуля forloop (цикл) включает следующие поля:

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

type

Тип модуля. Устанавливается значение forloop.

строка

modules

Массив описаний модулей, включенных в текущий цикл. См. описание поля.

массив

skip_failures

Возобновление выполнения цикла при ошибке.

Доступные значения:

  • true — если при выполнении какого-либо модуля в цикле возникнет ошибка, выполнение цикла начнется повторно, с новой итерации.

  • false — если при выполнении какого-либо модуля в цикле возникнет ошибка, выполнение цикла будет прервано.

логическое

parallel

Параллельное выполнение итераций цикла.

Доступные значения:

  • true — итерации цикла могут выполняться параллельно.

  • false — параллельное выполнение итераций цикла запрещено.

булево

parallelism

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

целое число

iterator

Параметры итератора. См. описание поля.

массив

Поле modules

В поле modules задается описание модулей, выполняемых в рамках этого цикла.

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

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

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

id

Идентификатор

строка

body

Массив записей, описывающих модули в цикле

массив

Поле iterator

В поле iterator задается описание настроек итератора. Итератор определяет количество итераций цикла и входные аргументы для каждой итерации.

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

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

type

Тип формата данных итератора.

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

  • static — статичный формат;

  • js — формат JavaScript.

строка

value или expr

Настройка количества итераций и входных аргументов итераций цикла.

  • Если выбран тип static, в поле value необходимо задать численные значения аргументов для каждой итерации value: [число1, число2, …​ ].

  • Если выбран тип js, в поле expr необходимо задать выражение на языке JavaScript. Выполненное выражение возвращает значения аргументов для каждой итерации: expr: [выражение1, выражение2, …​ ]. Количество аргументов в полях value или expr определяет количество итераций в цикле.

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

Пример описания модуля типа forloop в поле modules в схеме плейбука:

Цикл включает в себя два модуля. Для цикла разрешено параллельное выполнение пяти итераций.

В настройках итератора указано количество итераций (8) и входные аргументы для каждой итерации.

modules:
    # Идентификатор модуля цикла
    - id: "module_id"
    # Группа полей, описывающая цикл
      body:
        # Тип модуля - forloop.
        type: forloop
        # Блок описания модулей в составе цикла.
        modules:
            # Идентификатор первого модуля в составе цикла.
            - id: "2_1_module_id"
            # Группа полей, описывающая первый модуль.
              body:
                type: rawscript
                source: !py
                    def main(x):
                        return x
                input:
                    x:
                        type: js
                        expr: flow_input.iter.value

           # Идентификатор второго модуля в составе цикла.
           - id: "2_2_module_id"
              # Группа полей, описывающая второй модуль.
              body:
                type: identity
        # Параметры итератора
        iterator:
            # Тип формата данных итератора (статический).
            type: static
            # Выражение, задающее входные аргументы для каждой итерации цикла. Количество аргументов - 8, следовательно, цикл имеет 8 итераций.
            expr: "[2, 4, 6, 8, 10, 12, 14, 16]"
        # Разрешено параллельное выполнение итераций.
        parallel: true
        # Максимальное количество параллельных итераций.
        parallelism: 5
        # Если при выполнении какого-либо модуля в цикле возникнет ошибка, выполнение цикла начнется повторно, с новой итерации.
        skip_failures: true

Тип case

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

Описание типа модуля case (ветвление) включает следующие поля:

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

type

Тип модуля. Устанавливается значение case.

строка

default

См. описание поля.

массив

branches

См. описание поля.

массив

Поле default

В поле default задается описание модуля или модулей, выполняемых по умолчанию.

Структура каждого модуля включает обязательные поля id и body, а также другие требуемые поля.

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

id

Идентификатор модуля. Для цикла устанавливается значение forloop.

строка

body

Описание модуля. Набор полей зависит от типа модуля.

Поле branches

В поле branches задается описание модуля или модулей, запускаемых при выполнении определенных заданных условий.

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

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

summary

Описание ветки. Необязательное поле.

строка

condition

Условие выполнения. Указывается переменная и ее допустимые значения для выполнения условия.

modules

Массив описаний модулей, запускаемых при выполнении условия

Пример описания модуля типа case в поле modules в схеме плейбука:

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

modules:
    # Идентификатор модуля case
    - id: 1_module
      # Группа полей, описывающая ветвление
      body:
         # Тип модуля - case
         type: case
         # Блок, описывающий модули, запускаемые по умолчанию (если ни одно условие не выполнено)
         default:
           - id: 1_1_module
             body:
               type: script
               id: 64fe191d-3319-47ea-a87b-046c8df4032b
               input: {}
           - id: 1_2_module
             body:
                type: script
                id: 93fe803d-7375-456a-a28b-6c84hj73j02c
                input: {}
      # Блок, описывающий модули, запускаемые при выполнении указанных условий
      branches:
          # Необязательное описание первого ветвления
          - summary: branch_1
            # Условие первого ветвления
            condition: flow_input.age < 50
            # В поле modules размещается описание модулей, запускаемых при выполнении условия первого ветвления
            modules:
              - id: 1_3_module
                 body:
                    type: script
                    id: 66fa731d-9378-25wa-a93q-003c8df9031a
                    input: {}
         # Необязательное описание второго ветвления
         - summary: branch_2
           # Условие второго ветвления
           condition: flow_input.age < 100
           # В поле modules размещается описание модулей, запускаемых при выполнении условия второго ветвления
           modules:
               - id: 1_4_module
                 body:
                    type: script
                    id: 191dr623rf-9058-99ea-a23b-904c8df83564w
                    input: {}

Тип all

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

Описание типа модуля all включает следующие поля:

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

type

Тип модуля. Устанавливается значение all.

строка

branches

См. описание поля.

массив

parallel

Параллельное выполнение веток.

Доступные значения:

  • true — ветки могут выполняться параллельно.

  • false — параллельное выполнение веток запрещено. Ветки будут выполняться последовательно.

булево

Поле branches

В поле branches задается описание веток с модулями, запускаемыми для параллельного выполнения.

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

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

summary

Описание ветки. Необязательное поле.

строка

parallel

Параллельное выполнение модулей в ветке.

Доступные значения:

  • true — модули в ветке могут выполняться параллельно.

  • false — параллельное выполнение модулей в ветке запрещено. Модули будут выполняться последовательно.

булево

modules

Массив описаний модулей в ветке

массив

Пример описания модуля типа all в поле modules в схеме плейбука.

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

modules:
    # Идентификатор модуля case
    modules:
     - id: 1_module
       body:
         type: all
         # Блок, описывающий модули, запускаемые в ветках
         branches:
              # Описание первой ветки
              - summary: branch_1
                # Запрет параллельного запуска модулей в ветке
                parallel: false
                modules:
                  - id: 1_1_module
                    body:
                      type: script
                      id: 64fe191d-3319-47ea-a87b-046c8df4032b
                      input: {}
              # Описание второй ветки
              - summary: branch_2
                # Запрет параллельного запуска модулей в ветке
                parallel: false
                modules:
                 - id: 1_2_module
                  body:
                   type: script
                   id: 191dr623rf-9058-99ea-a23b-904c8f83564w
    input: {}
    # Ветки будут запущены параллельно
    parallel: true

Тип rawscript

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

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

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

type

Тип модуля. Устанавливается значение rawscript.

строка

source

Выполняемый код скрипта

input

Входные аргументы для выполнения кода скрипта

массив

tag

Тег скрипта

строка

Поле source

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

  • !bun — TypeScript, среда выполнения Bun;

  • !deno — TypeScript, среда выполнения Deno;

  • !py — Python;

  • !go — Go;

  • !pwsh — PowerShell;

  • !bash — Bash.

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

Пример описания модуля типа RawScript в поле modules в схеме плейбука
modules:
    # Идентификатор модуля
    - id: "1_module_id"
      # Группа полей, описывающая неопубликованный скрипт
      body:
        # Тип модуля - rawscript.
        type: rawscript
        # Входные аргументы.
        input:
            arg1:
               type: static
               value: 1
            arg2:
               type: static
               value: qwerty
            arg3:
               type: js
               expr: flow_input.input_arg
        # Описание языка выполнения скрипта.
        source: !py
           # Выполняемый код.
           print(123)

Тип identity

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

Описание модуля типа identity включает следующие поля:

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

type

Тип модуля. Устанавливается значение identity.

строка

Пример описания модуля типа identity в поле modules в схеме плейбука
modules:
    # Идентификатор модуля identity.
    - id: 1_module
      # Группа полей, описывающая модуль.
      body:
         # Тип модуля - identity.
         type: identity

Тип whileloop

Тип модуля whileloop используется для описания цикла (многократного повторения определенной последовательности модулей), выполняемого при соблюдении заданного условия.

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

Возможные сценарии использования:

  • Плейбук отправляет на обработку фрагменты какого-то массива данных. Цикл отправки будет выполняться, пока система не удостоверится, что переданы абсолютно все фрагменты.

  • Плейбук передает на внешний сервис данные для обработки. Объем данных, который сервис сочтет достаточным для обработки, заранее неизвестен. Цикл будет прерван, когда от сервиса поступит информация о том, что данные переданы в достаточном количестве.

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

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

type

Тип модуля. Устанавливается значение whileloop.

строка

modules

Описания модулей, включенных в цикл. См. описание поля.

объект

skip_failures

Возобновление выполнения цикла при ошибке.

Доступные значения:

  • true — если при выполнении какого-либо модуля в цикле возникнет ошибка, выполнение цикла начнется повторно, с новой итерации.

  • false — если при выполнении какого-либо модуля в цикле возникнет ошибка, выполнение цикла будет прервано.

логическое

Поле modules

В поле modules задается описание модулей, выполняемых в рамках этого цикла.

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

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

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

id

Идентификатор

строка

body

Тело модуля

объект

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

Описание модуля типа forloop в поле modules в схеме плейбука:

Цикл включает в себя два модуля.

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

  modules:
     # Идентификатор модуля цикла.
    - id: while_loop
      body:
        type: whileloop
        # Возможность возобновления выполнения цикла при ошибке.
        skip_failures: false
        modules:
          # Идентификатор первого модуля в составе цикла.
            - id: "2_1_module_id"
              # Группа полей, описывающая первый модуль.
              body:
                type: rawscript
                source: !py
                    def main(x):
                        return x
                input:
                    x:
                        type: js
                        expr: flow_input.iter.value

           # Идентификатор второго модуля в составе цикла.
           - id: "2_2_module_id"
             # Группа полей, описывающая второй модуль.
             body:
               type: identity
      # Возможность запуска остановленного модуля и всех последующих модулей.
      stop_after_if:
        expr: result.num_arg == 3
        skip_if_stopped: false

Тип approval

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

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

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

timeout_sec

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

целое число

message

Сопроводительное сообщение, отображаемое в момент ожидания согласования

текст