Скрипты

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

О скриптах

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

Работа со скриптом

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

Создание скрипта

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

Чтобы создать скрипт:

  1. Перейдите в раздел Экспертиза. Система отобразит список элементов экспертизы.

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

  3. Заполните поля скрипта, чтобы определить логику его работы.

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

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

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

Запуск скрипта

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

Чтобы запустить скрипт:

  1. Перейдите в раздел Экспертиза. Система отобразит список элементов экспертизы.

  2. Нажмите на строку скрипта в списке. Система отобразит в правой части экрана карточку этого скрипта с подробной информацией о нем.

  3. Убедитесь, что скрипт включен. Переключатель в карточке скрипта должен быть переведен в активное положение.

  4. Нажмите на кнопку Запустить в карточке скрипта. Скрипт будет запущен.

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

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

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

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

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

    • Если аргументы в скрипте отсутствуют, в воркер передается пустой JSON-файл.

    • Если имеются непереопределенные аргументы по умолчанию, аргументы будут подставлены в JSON-файл.

    • Если имеются переопределенные аргументы по умолчанию, именно они будут подставлены в JSON-файл.

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

  4. Если необходимо отдельно установить определенные зависимости скрипта, воркер производит установку зависимостей в рамках отдельной задачи. Для этого воркер скачивает зависимости из реестра зависимостей, установленного по умолчанию. Установленные зависимости в дальнейшем хранятся на этом воркере. Они используются при последующих выполнениях скрипта на этом воркере, что существенно сокращает время работы.

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

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

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

    Если такие данные сохранены в кэше, воркер предоставит их, что ускорит выполнение процесса.

    Пример

    Скрипт производит определенную трансформацию входных данных в выходные данные — принимает объемные входные данные, преобразует их в JSON-файл, ищет определенное поле и передает его на выход.

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

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

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

  8. Система помещает скрипт в специальную оболочку, позволяющую через библиотеку playbooks_sdk бесшовно получать доступ к переменным, элементам экспертизы, запускам и интеграциям с другими сервисами.

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

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

Изменение скрипта

Чтобы изменить скрипт:

  1. Перейдите в раздел Экспертиза. Система отобразит сведения об имеющихся элементах экспертизы.

  2. Нажмите на строку скрипта в списке. Система отобразит в правой части экрана карточку с подробной информацией о скрипте.

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

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

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

    • Для черновика: нажмите на кнопку Изменить в нижней части карточки.

  4. Внесите требуемые изменения в конфигурацию скрипта.

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

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

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

Удаление скрипта

Чтобы удалить скрипт:

  1. Перейдите в раздел Экспертиза. Система отобразит сведения об имеющихся элементах экспертизы.

  2. Нажмите на строку скрипта в списке. Система отобразит в правой части экрана карточку с подробной информацией о скрипте.

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

  4. Нажмите на кнопку Удалить. Система удалит скрипт и отобразит соответствующее уведомление. Удаленный скрипт будет исключен из списка элементов экспертизы.

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

  1. Перейдите в раздел Экспертиза. Система отобразит сведения об имеющихся элементах экспертизы.

  2. Установите флажки напротив тех элементов, которые вы хотите удалить, в левом столбце таблицы.

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

  4. Нажмите на кнопку Удалить. Система удалит выбранные элементы и отобразит соответствующее уведомление. Удаленные элементы будет исключены из списка элементов экспертизы.

Структура RObject-схемы скрипта и информация об API

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

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

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

id

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

строка

type

Тип элемента экспертизы

В скрипте здесь всегда устанавливается значение script.

name

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

строка

version

Версия скрипта в формате Semantic Versioning

строка
Пример заполненной структуры метаданных: 
id: script_ new_version
type: script
name: script_ new_version_name
version: 1.0.0

Поле source

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

Допустимые значения тега в поле source:

Тег Язык скрипта

!bun

TypeScript, среда выполнения Bun

!deno

TypeScript, среда выполнения Deno

!py

Python

!go

Go

!pwsh

PowerShell

!bash

Bash

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

Для всех языков, кроме PowerShell и Bash, в блоке кода обязательно должна быть определена функция main, являющаяся входной точкой скрипта. Аргументы этой функции, таким образом, будут входными аргументами скрипта.

Для языков PowerShell и Bash аргументы задаются с помощью глобальных переменных.

Доступ к компонентам платформы

Из SDK можно получать доступ к компонентам платформы (например, управлению доменами).

Синтаксис импортируемых зависимостей

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

TypeScript (bun, deno)

  • @expertise/<source_id> — будет импортироваться самая последняя версия скрипта;

  • @expertise/<source_id>@0.0.9 — будет импортироваться указанная версия скрипта, в данном случае, 0.0.9.

Здесь <source_id> — id элемента экспертизы типа Скрипт.

Пример 
id: bun_with_expertise_dependency
name: Bun with expertise dependency
version: 0.0.6
type: script
source: !bun |
  import { func } from '@expertise/bun_dependency_one_func@0.0.9'
  import { func2 } from '@expertise/bun_dependency_one_func_2'

  export async function main() {
    console.log('main f')
    func()
    console.log('main f2')
    func2()
  }

Задание значений аргументов в скрипте

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

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

Некоторые языки позволяют задавать значения для аргументов по умолчанию. В таком случае аргументы становятся опциональными.

Переменные окружения

Для скрипта можно задавать переменные окружения в следующем формате:

<KEY>=<value>

Здесь <KEY> — название переменной окружения, а <value> — значение переменной окружения.

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

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

Для задания тайм-аута скрипта используется переменная окружения TIMEOUT.

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

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

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

Использование API в скриптах

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

Языки, поддерживаемые системной библиотекой

В системе имеется собственная библиотека playbooks_sdk. Ее можно использовать при написании скриптов на следующих языках:

  • Python;

  • TypeScript (среды выполнения Bun и Deno);

  • Go;

  • VRL.

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

Доступ к переменным и к секретам

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

Использование переменных на примере языка Python:

import playbooks_sdk

playbooks_sdk.get_variable("u/user/foo")
playbooks_sdk.set_variable("u/user/foo", value)

Использование секретов на примере языка Python:

import playbooks_sdk

playbooks_sdk.get_secret("u/user/foo")
playbooks_sdk.set_secret("u/user/foo", value)

Работа с конфигурациями

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

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

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

Работа со схемами конфигураций

При написании скриптов на языке с сильной типизацией (например, TypeScript) можно получать схемы (типы) используемых конфигураций.

Поля настроек выполнения скрипта

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

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

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

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

concurrent_limit

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

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

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

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

целое число

concurrency_time_window_t

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

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

целое число

cache_ttl

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

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

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

целое число

Составление скрипта

Скрипт создается в три этапа:

  1. Описание блока метаданных.

  2. Описание блока исходного кода скрипта на допустимом языке.

  3. Описание блока настроек скрипта (опционально).

Метаданные скрипта

Заполните блок метаданных скрипта.

Код скрипта

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

Пример кода (среда Bun) 
# Тег, определяющий язык, на котором написан код скрипта.
source: !bun
    # Функция main - входная точка скрипта.
    export async function main() {
      console.log("BUN SCRIPT EXECUTED SUCCESSFULLY")
      return 0
    }

Настройки выполнения скрипта

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

Пример 1. Пример настроек
id: script_ new_version
type: script
name: script_ new_version_name
version: 1.0.0

source: !bun
    export async function main() {
        console.log("BUN SCRIPT EXECUTED SUCCESSFULLY");
        return 0;
    }

concurrent_limit: 3
    concurrency_time_window_t: 1
    cache_ttl: 1

Пример скрипта

# Блок метаданных.
id: script_new_version
type: script
name: script_new_version_name
version: 1.0.0

# Блок кода скрипта.
source: !bun
    export async function main() {
      console.log("BUN SCRIPT EXECUTED SUCCESSFULLY")
      return 0
    }

# Блок настроек.
concurrent_limit: 3
    concurrency_time_window_t: 1
    cache_ttl: 1

Дополнительные настройки скрипта

Настройки повторного запуска скрипта

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

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

+7 (499) 755 55 70 sales@rvision.ru

О компании Пользовательское соглашение Политика cookies