Wiki › Справка

Формулы для работы с параметрами

Это расширенная инструкция по внутренним функциям конструктора ботов Самбот с понятными примерами.

Математические операции

Сложение (`+`)

Оператор сложения позволяет складывать числа. Вы можете использовать его для сложения фиксированных чисел или значений из параметров.

Пример 1: Сложение фиксированных чисел

10 + 5 = 15

Пример 2: Сложение числа с параметром
Предположим, у пользователя в параметре {user:количество_товаров} хранится значение "3".

{user:количество_товаров} + 2 = 5

Пример 3: Сложение двух параметров
Предположим, у пользователя в {user:баланс_бонусов} хранится "100", а в {user:подарки} - "50".

{user:баланс_бонусов} + {user:подарки} = 150

Вычитание (`-`)

Оператор вычитания позволяет вычитать одно число из другого.

Пример 1: Вычитание фиксированного числа из параметра
Предположим, у пользователя в параметре {user:баланс} хранится "100".

{user:баланс} - 25 = 75

Пример 2: Вычитание одного параметра из другого
Предположим, у пользователя в {user:общая_сумма} хранится "500", а в {user:скидка} - "100".

{user:общая_сумма} - {user:скидка} = 400

Умножение (`*`)

Оператор умножения используется для умножения чисел.

Пример 1: Умножение параметра из Google Sheets на число
Предположим, в ячейке A1 таблицы Google Sheets с ID(внутренний id на платформе) 258 хранится значение "5".

{googlesheets:258:A1} * 100 = 500

Пример 2: Умножение двух параметров
Предположим, в {user:цена} хранится "20", а в {user:количество} - "3".

{user:цена} * {user:количество} = 60

Деление (`/`)

Оператор деления используется для деления чисел.

Пример 1: Деление одного параметра на другой
Предположим, у пользователя в {user:счёт} хранится "20", а в {user:делитель} - "10".

{user:счёт} / {user:делитель} = 2

Пример 2: Деление параметра на фиксированное число
Предположим, в {user:общее_количество} хранится "150".

{user:общее_количество} / 3 = 50

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

Объединение (`&`)

Оператор объединения (конкатенации) позволяет соединять текстовые строки.

Пример 1: Объединение текста и параметра
Предположим, у пользователя в {first_name} хранится "Артём".

"Имя: " & {first_name} = "Имя: Артём"

Пример 2: Объединение нескольких параметров и текста
Предположим, в {last_name} хранится "Иванов", а в {user:city} - "Москва".

{first_name} & " " & {last_name} & ", город: " & {user:city} = "Артём Иванов, город: Москва"

ДЛСТР (LEN)

Функция ДЛСТР (LEN) возвращает количество символов в текстовой строке.

Пример 1: Длина фиксированной строки

ДЛСТР("текст") = 5

Пример 2: Длина строки из параметра
Предположим, в {user:сообщение} хранится "Привет!".

ДЛСТР({user:сообщение}) = 7

Логические функции

ЕСЛИ (IF)

Функция ЕСЛИ (IF) позволяет выполнять логическую проверку. Если условие истинно, она возвращает одно значение; если ложно — другое.

Синтаксис: ЕСЛИ(условие; значение_если_истина; значение_если_ложь)

Пример 1: Проверка роста пользователя
Предположим, у пользователя в {user:Рост} хранится "176". Проверим рост, и если рост пользователя больше 160, то запишем "высокий", иначе - запишем "низкий"

ЕСЛИ({user:Рост} > 160; "высокий"; "низкий") = "высокий"

Пример 2: Проверка наличия товара на складе
Предположим, в {user:количество_на_складе} хранится "0".

ЕСЛИ({user:количество_на_складе} > 0; "Товар в наличии"; "Нет в наличии") = "Нет в наличии"

ЕЧИСЛО (ISNUMBER)

Функция ЕЧИСЛО (ISNUMBER) проверяет, является ли значение числом. Возвращает 1 (истина), если это число, и 0 (ложь), если нет.

Пример 1: Проверка числа

ЕЧИСЛО(2) = 1

Пример 2: Проверка текста

ЕЧИСЛО("abc") = 0

Пример 3: Использование с параметром
Предположим, в {user:возраст} хранится "25".

ЕЧИСЛО({user:возраст}) = 1

Если в {user:возраст} хранится "двадцать пять".

ЕЧИСЛО({user:возраст}) = 0

И (AND)

Функция И (AND) возвращает 1 (истина), если все условия, указанные в ней, выполняются. В противном случае возвращает 0 (ложь).

Синтаксис: И(условие1; условие2; ...)

Пример 1: Проверка нулевого баланса и баллов
Предположим, у пользователя в {user:Баланс} и {user:Баллы} хранится "0".

И({user:Баланс} = 0; {user:Баллы} = 0) = 1

Пример 2: Проверка возраста и города
Предположим, в {user:возраст} хранится "18", а в {user:город} - "Санкт-Петербург".

И({user:возраст} >= 18; {user:город} = "Москва") = 0

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

ИЛИ (OR)

Функция ИЛИ (OR) возвращает 1 (истина), если хотя бы одно из указанных условий выполняется. В противном случае возвращает 0 (ложь).

Синтаксис: ИЛИ(условие1; условие2; ...)

Пример 1: Проверка положительного баланса или баллов
Предположим, у пользователя в {user:Баланс} хранится "50", а в {user:Баллы} - "0".

ИЛИ({user:Баланс} > 0; {user:Баллы} > 0) = 1

В этом случае условие {user:Баланс} > 0 истинно, поэтому функция возвращает 1.

Пример 2: Проверка скидки или акции
Предположим, в {user:есть_скидка} хранится "нет", а в {user:участвует_в_акции} - "да".

ИЛИ({user:есть_скидка} = "да"; {user:участвует_в_акции} = "да") = 1

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

ЕСЛИ(И({user:возраст} >= 18; {user:город} = "Москва"); "Может посетить выставку"; "Не может посетить выставку") = Не может посетить выставку

Функции для чисел

МИН (MIN)

Функция МИН (MIN) возвращает наименьшее значение из списка чисел.

Синтаксис: МИН(число1; число2; ...)

Пример 1: Минимальное из фиксированных чисел

МИН(1; 2; 3) = 1

Пример 2: Минимальное значение среди параметров
Предположим, в {user:стоимость_товара1} хранится "100", а в {user:стоимость_товара2} - "75".

МИН({user:стоимость_товара1}; {user:стоимость_товара2}; 50) = 50

Пример 3: Минимальное значение среди значений параметра с типом "хранить все значения"
Предположим, в {user:числа} хранятся значения "4, 12, 2, 89, 23, 17"

МИН({user:стоимость_товара1:1-}) = 2

МАКС (MAX)

Функция МАКС (MAX) возвращает наибольшее значение из списка чисел.

Синтаксис: МАКС(число1; число2; ...)

Пример 1: Максимальное из фиксированных чисел

МАКС(1; 2; 3) = 3

Пример 2: Максимальное значение среди параметров
Предположим, в {user:рейтинг1} хранится "4", а в {user:рейтинг2} - "5".

МАКС({user:рейтинг1}; {user:рейтинг2}; 3) = 5

ОКРУГЛ (ROUND)

Функция ОКРУГЛ (ROUND) округляет число до указанного количества десятичных знаков.

Синтаксис: ОКРУГЛ(число; количество_знаков)

Пример 1: Округление до двух знаков после запятой

ОКРУГЛ(3.1415926535; 2) = 3.14

Пример 2: Округление до целого числа (ноль знаков)

ОКРУГЛ(7.89; 0) = 8

Пример 3: Округление с использованием параметра
Предположим, в {user:стоимость_с_ндс} хранится "123.456".

ОКРУГЛ({user:стоимость_с_ндс}; 1) = 123.5

ПИ (PI)

Функция ПИ (PI) возвращает значение числа Пи (π) с высокой точностью. Не требует аргументов.

Пример:

ПИ() = 3.141592653589793

СРЗНАЧ (AVERAGE)

Функция СРЗНАЧ (AVERAGE) вычисляет среднее арифметическое для набора числовых значений. Вы можете передавать как фиксированные числа, так и значения из параметров.

Синтаксис: СРЗНАЧ(число1; число2; ...)

Пример 1: Среднее арифметическое фиксированных чисел и параметра
Предположим, в ячейке A1 таблицы Google Sheets с ID 111 хранится значение "9".

СРЗНАЧ(2; 4; {googlesheets:111:A1}) = 5

(Расчёт: (2 + 4 + 9) / 3 = 5)

Пример 2: Среднее арифметическое из нескольких параметров
Предположим, в {user:оценка1} хранится "8", а в {user:оценка2} - "7".

СРЗНАЧ({user:оценка1}; {user:оценка2}; 9) = 8

(Расчёт: (8 + 7 + 9) / 3 = 8)

СУММ (SUM)

Функция СУММ (SUM) суммирует все числовые значения, переданные в качестве аргументов.

Синтаксис: СУММ(число1; число2; ...)

Пример 1: Сумма фиксированных чисел и параметра
Предположим, у пользователя в параметре {user:Число} хранится значение "3".

СУММ(1; 2; {user:Число}) = 6

(Расчёт: 1 + 2 + 3 = 6)

Пример 2: Сумма значений из нескольких параметров
Предположим, в {user:расход_продукты} хранится "500", а в {user:расход_транспорт} - "150".

СУММ({user:расход_продукты}; {user:расход_транспорт}; 200) = 850

RANDBETWEEN (СЛУЧМЕЖДУ)

Функция СЛУЧМЕЖДУ (RANDBETWEEN) генерирует случайное целое число в заданном диапазоне, включая оба граничных значения.

Синтаксис: СЛУЧМЕЖДУ(нижнее_значение; верхнее_значение)

Пример 1: Случайное число от 1 до 10

СЛУЧМЕЖДУ(1; 10) = 7 (может быть любое число от 1 до 10)

Пример 2: Случайное число для ID заказа

СЛУЧМЕЖДУ(1000; 9999) = 5432 (например, для генерации четырёхзначного ID)

Функции для поиска в тексте

НАЙТИ (FIND)

Функция НАЙТИ (FIND) возвращает начальную позицию (порядковый номер символа) первого вхождения искомой подстроки в тексте. Учитывает регистр символов. Вы можете указать необязательный аргумент "начальная_позиция" для поиска, начиная с определенного символа.

Синтаксис: НАЙТИ(искомая_подстрока; текст; [начальная_позиция])

Пример 1: Поиск с учетом регистра

НАЙТИ("грека"; "Ехал грека через реку, видит грека – в реке рак"; 1) = 6

(Поиск начинается с 1-го символа. "грека" находится, начиная с 6-го символа)

Пример 2: Поиск, начиная с определенной позиции

НАЙТИ("грека"; "Ехал грека через реку, видит грека – в реке рак"; 10) = 30

(Поиск начинается с 10-го символа. Первое вхождение "грека" после 10-го символа начинается с 30-го символа)

Пример 3: Использование с параметрами
Предположим, в {user:фраза} хранится "Яблоко и банан".

НАЙТИ("банан"; {user:фраза}; 1) = 10

ПОИСК (SEARCH)

Функция ПОИСК (SEARCH) также возвращает начальную позицию первого вхождения искомой подстроки, но, в отличие от НАЙТИ, она не учитывает регистр символов. Так же имеет необязательный аргумент "начальная_позиция".

Синтаксис: ПОИСК(искомая_подстрока; текст; [начальная_позиция])

Пример 1: Поиск без учета регистра

ПОИСК("хвост"; "Нос крючком, Хвост пятачком"; 1) = 14

(Несмотря на то, что в тексте "Хвост" написан с заглавной буквы, функция находит его, начиная с 14-го символа.)

Пример 2: Поиск, начиная с определенной позиции, без учета регистра

ПОИСК("мир"; "Привет, Мир! Как дела, мир?"; 10) = 24

(Поиск "мир" начинается с 10-го символа. Первое вхождение "мир" после 10-го символа начинается с 24-го символа.)

Функции для работы с JSON

TOJSON

Функция TOJSON преобразует переданное значение (например, список из параметра) в строку в формате JSON. Это полезно для передачи данных в другие системы или для работы с JSON-структурами.

Синтаксис: TOJSON(значение)

Пример 1: Преобразование параметра с типом "хранить все значения" в JSON-массив
Предположим, параметр {user:Языки:1-} содержит значения "Английский", "Русский", "Тайский".

TOJSON({user:Языки:1-}) = "["Английский", "Русский", "Тайский"]"

Пример 2: Преобразование одиночного значения в JSON-строку

TOJSON("Привет") = "Привет"

Пример 3: Преобразование числа в JSON-число

TOJSON(123) = "123"

FROMJSON

Функция FROMJSON выполняет обратное действие: она преобразует строку в формате JSON обратно в соответствующий тип данных (например, массив или объект).

Синтаксис: FROMJSON(JSON_строка)

Пример 1: Преобразование JSON-массива в список и его объединение

JOIN(", "; FROMJSON("["Английский", "Русский", "Тайский"]")) = "Английский, Русский, Тайский"

Здесь FROMJSON превращает строку в список, который затем JOIN объединяет в одну строку

Пример 2: Преобразование JSON-массива в список БЕЗ объединения

FROMJSON("["Английский", "Русский", "Тайский"]") = "Тайский"

ВАЖНО! Как можно заметить, в результат записалось только одно значение - "Тайский". То есть в параметр сохранится последний элемент массива. Так работает для параметра с типом "Хранить последнее значение".
Если тип параметр будет "Хранить первое значение", то в результат запишется первый элемент массива "Английский.
А если тип параметра "Хранить все значения", то в результат будут записаны все элементы массива по очереди.

JSONPATH

Функция JSONPATH позволяет извлекать данные из JSON-структуры, используя синтаксис JSONPath. Это мощный инструмент для навигации по сложным JSON-объектам и массивам.

Синтаксис: JSONPATH(JSON_данные; JSONPath_выражение; [значение_по_умолчанию])
JSON_данные могут быть либо строкой JSON, либо результатом функции FROMJSON.
значение_по_умолчанию - необязательный аргумент, который будет возвращён, если путь не найден.

Пример 1: Извлечение всех ID из списка объектов

TOJSON(JSONPATH("{"ids":[{"id":1},{"id":3}]}"; "$.ids..id")) = "[1,3]"

Здесь "$.ids..id" означает: "взять элемент ids, затем найти все элементы с ключом id внутри него, независимо от вложенности". Результатом будет массив [1, 3], который TOJSON преобразует в строку.

Пример 2: Комбинирование FROMJSON и JSONPATH

TOJSON(JSONPATH(FROMJSON("{"ids":[{"id":1},{"id":3}]}"); "$.ids..id")) = "[1,3]"

Это эквивалентно предыдущему примеру, но демонстрирует типичное использование FROMJSON для парсинга строки в JSON-объект, прежде чем применить JSONPATH.

Пример 3: Использование значения по умолчанию

JSONPATH("{"; "$.id"; "error") = "error"

Здесь JSON-строка некорректна (просто {), путь $.id не может быть найден, и функция возвращает "error".

JSONPATHSMART (JP)

Функция JSONPATHSMART (или её короткий псевдоним JP) является более удобным способом для извлечения значений из JSON. Она автоматически пытается преобразовать переданную строку в JSON, если это возможно, что упрощает её использование.

Синтаксис: JSONPATHSMART(JSON_строка_или_объект; JSONPath_выражение)

Пример 1: Извлечение значения по ключу

JSONPATHSMART("{"key": "value"}"; "$.key") = "value"

Пример 2: Использование короткого псевдонима

JP("{"key": "value"}"; "$.key") = "value"

Пример 3: Извлечение элемента из массива по индексу

JP("{"data":["a","b","c"]}"; "$.data[1]") = "b"

Функции для работы с датами и временем

Самбот работает с датами в формате d.m.Y H:i:s (день.месяц.год часы:минуты:секунды).

DATEVALUE

Функция DATEVALUE пытается преобразовать текстовую строку в дату и время в стандартном формате Самбота. Если строка не может быть преобразована, результат не будет возвращён.

Синтаксис: DATEVALUE(строка_даты_времени)

Пример 1: Преобразование даты без времени

DATEVALUE("01.02.2024") = "01.02.2024 00:00:00"

Пример 2: Преобразование даты с временем

DATEVALUE("25.12.2023 14:30:00") = "25.12.2023 14:30:00"

Пример 3: Преобразование из другого формата (может зависеть от региональных настроек)
Хотя официальный формат d.m.Y, иногда система может распознавать другие распространённые форматы.

DATEVALUE("2024-02-01") = "01.02.2024 00:00:00" (если формат распознан)

DATEADD

Функция DATEADD увеличивает (добавляет) к заданной дате указанный интервал времени. Интервал задаётся в формате ISO 8601 Duration.

Синтаксис: DATEADD(дата; интервал)

Пример 1: Добавление одного дня

DATEADD("01.02.2024"; "P1D") = "02.02.2024 00:00:00"

(P1D означает "Период 1 День")

Пример 2: Добавление 5 часов и 30 минут

DATEADD("01.02.2024 10:00:00"; "PT5H30M") = "01.02.2024 15:30:00"

(PT5H30M означает "Период Времени 5 Часов 30 Минут")

Пример 3: Добавление 1 года и 2 месяцев

DATEADD("01.01.2024"; "P1Y2M") = "01.03.2025 00:00:00"

DATESUB

Функция DATESUB уменьшает (вычитает) из заданной даты указанный интервал времени. Интервал также задаётся в формате ISO 8601 Duration.

Синтаксис: DATESUB(дата; интервал)

Пример 1: Вычитание одного дня

DATESUB("01.02.2024"; "P1D") = "31.01.2024 00:00:00"

Пример 2: Вычитание 2 недель

DATESUB("15.03.2024 12:00:00"; "P2W") = "01.03.2024 12:00:00"

(P2W означает "Период 2 Недели")

DATEDIF (РАЗНДАТ)

Функция DATEDIF (РАЗНДАТ) вычисляет разницу между двумя датами в указанных единицах.

Синтаксис: DATEDIF(начальная_дата; конечная_дата; единица_измерения)

Доступные единицы измерения:

Y: Годы (полные)
M: Месяцы (полные)
D: Дни
H: Часы
I: Минуты
S: Секунды
MD: Разница в днях, без учёта месяцев и лет
YM: Разница в месяцах, без учёта лет
YD: Разница в днях, без учёта годов

Пример 1: Разница в полных годах

DATEDIF("28.10.1981"; "01.02.2024"; "Y") = 42

Пример 2: Разница в полных месяцах

DATEDIF("28.10.2020"; "28.09.2024"; "M") = 47

Пример 3: Разница в днях

DATEDIF("28.10.2023"; "27.10.2024"; "D") = 365

Пример 4: Разница в часах

DATEDIF("27.10.2024 12:00:00"; "28.10.2024 11:30:00"; "H") = 23

Пример 5: Разница в минутах

DATEDIF("28.10.2024 12:00:00"; "28.10.2024 12:30:00"; "I") = 30

Пример 6: Разница в секундах

DATEDIF("28.10.2024 12:00:00"; "28.10.2024 12:00:45"; "S") = 45

Пример 7: Разница в днях без учёта месяцев и лет (для дней рождения)

DATEDIF("28.10.1981"; "27.10.2024"; "MD") = 29

Пример 8: Разница в месяцах без учёта годов

DATEDIF("28.10.1981"; "27.10.2024"; "YM") = 11

Пример 9: Разница в днях без учёта годов

DATEDIF("28.10.1981"; "27.10.2024"; "YD") = 365

DATEFORMAT

Функция DATEFORMAT позволяет форматировать дату и время в различных представлениях, используя специальные символы форматирования. Также можно указать язык для названий дней недели и месяцев.

Синтаксис: DATEFORMAT(дата; формат; [язык])

Символы форматирования (примеры, полный список по ссылке):

j: День месяца без ведущего нуля (1-31)
d: День месяца с ведущим нулём (01-31)
D: Краткое название дня недели (Пн, Вт...)
l: Полное название дня недели (Понедельник, Вторник...)
n: Номер месяца без ведущего нуля (1-12)
m: Номер месяца с ведущим нулём (01-12)
M: Краткое название месяца (янв, фев...)
F: Полное название месяца (Январь, Февраль...)
f: Полное название месяца в родительном падеже (января, февраля...) - часто используется в русском языке
N: Номер дня недели (1 для понедельника, 7 для воскресенья)
y: Год в двух цифрах (81)
Y: Год в четырёх цифрах (1981)
W: Номер недели года (например, 23)
z: День года (от 0 до 365)
H: Часы в 24-часовом формате (00-23)
i: Минуты (00-59)
s: Секунды (00-59)
U: Преобразует дату в UNIX формат

Пример 1: Форматирование с различными элементами даты/времени

DATEFORMAT("05.06.1981 10:22:53"; "j, d, D, l, n, m, M, F, f, N, y, Y, W, z") = "5, 05, Fri, Friday, 6, 06, Jun, June, June, 5, 81, 1981, 23, 155"

(Обратите внимание, что f даёт "June" в английском, но для русского будет склоняться)

Пример 2: Форматирование с указанием английского языка

DATEFORMAT("05.06.1981 10:22:53"; "j, d, D, l, n, m, M, F, f, N, y, Y, W, z"; "en") = "5, 05, Fri, Friday, 6, 06, Jun, June, June, 5, 81, 1981, 23, 155"

Пример 3: Форматирование с указанием русского языка

DATEFORMAT("05.06.1981 10:22:53"; "j, d, D, l, n, m, M, F, f, N, y, Y, W, z"; "ru") = "5, 05, Пт, Пятница, 6, 06, июн, июня, июнь, 5, 81, 1981, 23, 155"

Здесь видно, как D, l, M, F, f изменяются в зависимости от языка.

Пример 4: Вывод текущей даты и времени в формате "DD.MM.YYYY HH:MM"

DATEFORMAT(DATEVALUE({user:date_time}); "d.m.Y H:i")

(Предполагается, что {user:date_time} содержит текущее время, и DATEVALUE его корректно парсит)

Функции для сортировки и кодирования

SORT

Функция SORT сортирует переданные значения по возрастанию (алфавитному для строк, числовому для чисел).

Синтаксис: SORT(значение1; значение2; ...)

Пример 1: Сортировка смешанных типов данных

JOIN(", "; SORT("10"; "1"; "2"; "a"; "c"; "b")) = "1, 2, 10, a, b, c"

(Числа сортируются как числа, строки как строки, затем числовые значения идут перед строковыми)

RSORT

Функция RSORT сортирует переданные значения по убыванию (в обратном алфавитном порядке для строк, в обратном числовом для чисел).

Синтаксис: RSORT(значение1; значение2; ...)

Пример 1: Обратная сортировка смешанных типов данных

JOIN(", "; RSORT("10"; "1"; "2"; "a"; "c"; "b")) = "c, b, a, 10, 2, 1"

TOBASE64

Функция TOBASE64 кодирует текстовую строку в формат Base64. Используется для безопасной передачи бинарных данных или текста.

Синтаксис: TOBASE64(строка)

Пример:

TOBASE64("test") = "dGVzdA=="

FROMBASE64

Функция FROMBASE64 декодирует строку из формата Base64 обратно в исходную текстовую строку.

Синтаксис: FROMBASE64(Base64_строка)

Пример:

FROMBASE64("dGVzdA==") = "test"

Функции для работы с массивами (списками)

ARRAYFIND

Функция ARRAYFIND находит индекс (позицию) элемента в массиве. Нумерация индексов начинается с 0. Вы можете искать по конкретному значению или использовать лямбда-функцию для более сложного условия поиска.

Синтаксис:

ARRAYFIND(массив; значение)
ARRAYFIND(массив; LAMBDA(val; [key]; условие)) – val и key это аргументы лямбда-функции и вы можете их назвать как вам удобно в ваших формулах. Val - это значение в массиве, key - это индекс этого значения

Пример 1: Поиск по значению

ARRAYFIND(FROMJSON("[1, 5, 12]"); 5) = 1

(Элемент 5 находится по индексу 1 в массиве [1, 5, 12])

Пример 2: Поиск с использованием лямбда-функции (по значению)

ARRAYFIND(FROMJSON("[1, 5, 12]"); LAMBDA(x, x = 5)) = 1

(Лямбда-функция LAMBDA(x, x = 5) проверяет, равно ли значение x пяти.)

Пример 3: Поиск с использованием лямбда-функции (по индексу)
Предположим, нужно найти элемент на определённой позиции.

ARRAYFIND(FROMJSON("[1, 5, 12]"); LAMBDA(val; key; key = 2)) = 2

(Лямбда-функция LAMBDA(val; key; key = 2) проверяет, равен ли индекс key двум. В данном случае, это значение 12.)

ARRAYREMOVE

Функция ARRAYREMOVE удаляет элемент из массива по значению или по условию, заданному лямбда-функцией. Возвращает новый массив без удалённых элементов.

Синтаксис:

ARRAYREMOVE(массив; значение)
ARRAYREMOVE(массив; LAMBDA(val; [key]; условие))

Пример 1: Удаление по значению

TOJSON(ARRAYREMOVE(FROMJSON("[1, 5, 12]"); 5)) = "[1,12]"

(Удаляется значение 5.)

Пример 2: Удаление с использованием лямбда-функции (по значению)

TOJSON(ARRAYREMOVE(FROMJSON("[1, 5, 12]"); LAMBDA(val; key; val = 5))) = "[1,12]"

(Эквивалентно предыдущему, но с лямбдой.)

Пример 3: Удаление с использованием лямбда-функции (по индексу)

TOJSON(ARRAYREMOVE(FROMJSON("[1, 5, 12]"); LAMBDA(val; key; key = 2))) = "[1,5]"

(Удаляется элемент с индексом 2 (значение 12).)

ARRAYADD

Функция ARRAYADD добавляет элемент в массив. Вы можете добавить его в конец массива или по указанному индексу.

Синтаксис:

ARRAYADD(массив; элемент) (добавляет в конец)
ARRAYADD(массив; элемент; индекс) (добавляет по указанному индексу)

Пример 1: Добавление элемента в конец массива

TOJSON(ARRAYADD(FROMJSON("[1, 5, 12]"); 11)) = "[1,5,12,11]"

Пример 2: Добавление элемента по определённому индексу

TOJSON(ARRAYADD(FROMJSON("[1, 5, 12]"); 11; 1)) = "[1,11,5,12]"

(Элемент 11 добавляется на позицию с индексом 1.)

ARRAYREPLACE

Функция ARRAYREPLACE заменяет элемент в массиве по указанному индексу.

Синтаксис: ARRAYREPLACE(массив; новый_элемент; индекс)

Пример:

TOJSON(ARRAYREPLACE(FROMJSON("[1, 5, 12]"); 11; 1)) = "[1,11,12]"

(Элемент по индексу 1 (было 5) заменяется на 11.)

FOREACH

Функция FOREACH выполняет итерацию по каждому элементу массива и применяет к нему лямбда-функцию. Возвращает новый массив, содержащий результаты применения лямбда-функции к каждому элементу.

Синтаксис: FOREACH(массив; LAMBDA(val; [key]; выражение))

Пример 1: Добавление префикса к каждому значению

JOIN(", "; FOREACH(FROMJSON("[1, 5, 12]"); LAMBDA(val; "значение: "&val))) = "значение: 1, значение: 5, значение: 12"

(К каждому числовому значению добавляется строка "значение: ", и все значение объединяются в одну строку функцией JOIN)

Пример 2: Форматирование вывода с использованием индекса и значения

JOIN(", "; FOREACH(FROMJSON("[1, 5, 12]"); LAMBDA(val; key; key&": "&val))) = "0: 1, 1: 5, 2: 12"

(Для каждого элемента создаётся строка "индекс: значение".)

Функции для работы со строками (регистр)

UPPER (ПРОПИСН)

Функция UPPER (ПРОПИСН) преобразует все символы текстовой строки в верхний регистр.

Синтаксис: UPPER(строка)

Пример:

UPPER("test") = "TEST"

LOWER (СТРОЧН)

Функция LOWER (СТРОЧН) преобразует все символы текстовой строки в нижний регистр.

Синтаксис: LOWER(строка)

Пример:

LOWER("TEST") = "test"

UPPERFIRST (ПРОПИСНПЕРВ)

Функция UPPERFIRST (ПРОПИСНПЕРВ) преобразует только первый символ строки в верхний регистр, оставляя остальные символы без изменений.

Синтаксис: UPPERFIRST(строка)

Пример:

UPPERFIRST("test") = "Test"

UPPERFIRST("another test") = "Another test"

Функции для создания JSON-структур

JSONOBJECT

Функция JSONOBJECT создаёт JSON-объект из переданных пар "ключ-значение".

Синтаксис: JSONOBJECT(ключ1; значение1; ключ2; значение2; ...)

Пример:

TOJSON(JSONOBJECT("ключ1"; "значение1"; "ключ2"; "значение2")) = {"ключ1":"значение1","ключ2":"значение2"}

Пример 2: Создание объекта пользователя из параметров
Предположим, в {user:имя} хранится "Анна", а в {user:возраст} - "28".

TOJSON(JSONOBJECT("name"; {user:имя}; "age"; {user:возраст}; "is_active"; true)) = "{"name":"Анна","age":"28","is_active":true}"

JSONARRAY

Функция JSONARRAY создаёт JSON-массив из переданных значений.

Синтаксис: JSONARRAY(значение1; значение2; ...)

Пример:

TOJSON(JSONARRAY("значение1"; "значение2")) = "["значение1","значение2"]"

Пример 2: Создание массива из значений параметра
Предположим, {user:выбранные_товары:1-} содержит "Молоко", "Хлеб".

TOJSON(JSONARRAY({user:выбранные_товары:1-})) = ОШИБКА

Будет ошибка, так как функция JSONARRAY должна содержать не менее двух аргументов. В данном случае запись {user:выбранные_товары:1-} это один аргумент в виде строки "Молоко, Хлеб"

Вспомогательные функции

NL

Функция NL() возвращает символ новой строки (\n). Это полезно для форматирования текста в сообщениях бота или для создания многострочных записей в параметрах.

Синтаксис: NL()

Пример 1: Использование для создания новой строки

"Строка 1" & NL() & "Строка 2" = "Строка 1
Строка 2"

Пример 2: Объединение элементов параметра с новой строки
Предположим, в {user:param:1-} содержатся значения 1, 5, 12.

JOIN(NL(); {user:param:1-}) = "1
5
12"

Функции для работы с параметрами

PARAMID

Функция PARAMID возвращает внутренний ID конкретного значения параметра. Это особенно полезно для параметров с типом "хранить все значения", где каждое сохранённое значение имеет свой уникальный ID. Вы можете найти ID по порядковому номеру значения (позиции) в параметре или по условию, используя лямбда-функцию. В отличии от массивов, позиция значения для функций этого раздела начинается с 1 (единицы).
Этот ID необходим только для работы с функциями PARAM..

Важно: Первый аргумент функции — название параметра в кавычках, без фигурных скобок.

Синтаксис:

PARAMID("название_параметра"; позиция_значения) (позиция начинается с 1)
PARAMID("название_параметра"; LAMBDA(val; [key]; условие))

Пример 1: Получение ID первого значения параметра
Предположим {user:param} содержит значения: test, 3, value. Внутренние ID у этих параметров 3, 23, 24 соответственно.

PARAMID("user:param"; 1) = 3

Возвращает ID первого значения параметра

Пример 2: Получение ID значения по его содержимому
Если {user:param} содержит значение "test".

PARAMID("user:param"; LAMBDA(v; k; v = "test")) = 3

Возвращает ID того значения, которое равно "test". Если таких значений несколько:
– при сохранении в параметр "хранить первой значение" вернёт ID первого найденного значения
– при сохранении в параметр "хранить последнее значение" вернёт ID последнего найденного значения
– при сохранении в параметр "хранить все значения" вернёт ID всех найденных значения, записав их по очереди

Пример 3: Получение ID по определённому индексу
Если {user:param} содержит значения: test, 3, value. Внутренние ID у этих параметров 3, 23, 24 соответственно.

PARAMID("user:param"; LAMBDA(v; k; k = 2)) = 23

Возвращает ID значения на позиции с индексом 2 (то есть второго элемента), если такой существует.

PARAMREMOVE

Функция PARAMREMOVE удаляет значение параметра по его ID. Это мощная функция для управления параметрами с типом "хранить все значения"

В режимах параметра "хранить первое/последнее/все значение(я)" она возвращает (сохраняет в указанный в названии параметр) количество удаленных значений.
В режиме "Изменение значения" удаляет значение параметра без сохранения дополнительной информации (просто очищает его).

Синтаксис: PARAMREMOVE(ID_значения_параметра)

Пример 1: Удаление по конкретному ID
Предположим, вы ранее получили ID значения = 3 с помощью PARAMID.

PARAMREMOVE(3) = 1

Удаляет значение параметра с ID = 3 и возвращает 1, так как было удалено одно значение.

Пример 2: Удаление значений по условию (через LAMBDA и PARAMID)
Если {user:Параметр3} с типом "хранить все значения" содержит значения: 2, 3, 14, 3, 2

PARAMREMOVE(PARAMID("user:Параметр3"; LAMBDA(val; key; val < 3))) = 2

(Сначала PARAMID найдёт ID всех значений, которые меньше 3 (то есть 2 и 2). Затем PARAMREMOVE удалит эти значения. Вернёт 2, так как было удалено два значения.)

Пример 3: Удаление значения по индексу (через LAMBDA и PARAMID)
Если {user:Параметр3} содержит значения: 2, 3, 14, 3, 2.

PARAMREMOVE(PARAMID("user:Параметр3"; LAMBDA(val; key; key = 3))) = 1

(Удаляет значение, которое находится на позиции с индексом 3 (третий элемент = 14). Возвращает 1.)

PARAMREPLACE

Функция PARAMREPLACE заменяет существующее значение параметра на новое. Как и PARAMREMOVE, она работает с ID значений параметра.

В режимах параметра "хранить первое/последнее/все значение(я)" она возвращает количество заменённых значений.
В режиме "Изменение значения" заменяет значение параметра без сохранения дополнительной информации.

Синтаксис: PARAMREPLACE("название_параметра"; новое_значение; ID_значения_параметра_или_условие)

Пример 1: Замена по конкретному ID
Предположим, мы хотим заменить значение параметра user:Параметр3 с ID = 1 на "новое значение".

PARAMREPLACE("user:Параметр3"; "новое значение"; 1) = 1

Заменяет значение с ID = 1 и возвращает 1.

Пример 2: Замена значений по условию (через LAMBDA)
Если {user:Параметр3} содержит значения: 2, 3, 14, 3, 2.

PARAMREPLACE("user:Параметр3"; "новое значение"; LAMBDA(val; key; val = 3)) = 2

Найдет все значения, равные 3, и заменит их на "новое значение". Возвращает 2, так как было заменено два значения. В параметре будут значения 2, новое значение, 14, новое значение, 2

Пример 3: Замена значения по индексу (через LAMBDA)
Если {user:Параметр3} содержит значения: 2, 3, 14, 3, 2.

PARAMREPLACE("user:Параметр3"; "новое значение"; LAMBDA(val; key; key = 4)) = 1

Заменит значение на позиции с индексом 4 (четвертый элемент = 3). Возвращает 1.

HASH (ХЭШ)

Функция HASH (ХЭШ) преобразует заданную текстовую строку в криптографический хеш, используя указанный алгоритм. Хеширование — это односторонний процесс, который создаёт уникальный "отпечаток" данных фиксированной длины. Это полезно для проверки целостности данных, безопасного хранения паролей (когда сравнивается не сам пароль, а его хеш) и других задач, где нужно быстро сравнить данные без их прямого раскрытия.

Синтаксис: HASH(алгоритм; строка)

Доступные алгоритмы:

"md5"
"sha1"
"sha224"
"sha256"
"sha384"
"sha512"

Пример 1: MD5 хеш для строки "text"

HASH("md5"; "text") = "1cb251ec0d568de6a4bf74534882e989"

Пример 2: SHA256 хеш для строки "Hello World!"

HASH("sha256"; "Hello World!") = "c0535e4be2b79ffd93291305436bf889314e4ffcd5e06dffbe8ef9e0816993c8"

Пример 3: Сравнение хешей для проверки пароля (в сценарии бота)
Предположим, у вас в базе хранится SHA256 хеш пароля "secretpass", и пользователь вводит "secretpass".

ЕСЛИ(HASH("sha256"; {user:введенный_пароль}) = {global:пароль_хеш_из_базы}; "Пароль верный!"; "Неверный пароль.")

Если {user:введенный_пароль} = "secretpass", а {global:пароль_хеш_из_базы} = "7e7a59a9a3b6d2149b25141b714b7e7a59a9a3b6d2149b25141b714b7e7a59a9", то результат будет "Пароль верный!".

FROMJWT

Функция FROMJWT проверяет цифровую подпись JWT (JSON Web Token) с использованием указанного публичного ключа и, в случае успешной проверки, возвращает содержимое токена в формате JSON. JWT часто применяется для авторизации, передачи информации о пользователе и других задач, связанных с безопасностью.

Синтаксис: FROMJWT(токен; публичный_ключ)

Параметры:

токен — строка, содержащая JWT.
публичный_ключ — открытый ключ, с помощью которого проверяется подпись токена.

Результат: JSON-объект с полезной нагрузкой (payload) токена, если подпись корректна. Если подпись не проходит проверку, возвращается ошибка.

Пример 1: Разбор JWT с публичным ключом

FROMJWT("eyJhbGciOi..."; "-----BEGIN PUBLIC KEY-----...") 
= {"name": "John Doe"}

FROMJWK (ИЗ JWK В ПУБЛИЧНЫЙ КЛЮЧ)

Функция FROMJWK преобразует ключ в формате JWK (JSON Web Key) в стандартный публичный ключ, который можно использовать для проверки цифровых подписей или для операций шифрования. Формат JWK применяется в современных протоколах безопасности (например, OAuth 2.0, OpenID Connect) для удобного обмена ключами в JSON-формате.

Синтаксис: FROMJWK(jwk)

Параметры:

jwk — строка с JSON-объектом ключа в формате JWK.

Результат: публичный ключ в строковом виде, который можно передавать в функцию FROMJWT для проверки токенов.

Пример 1: Конвертация JWK в публичный ключ

FROMJWK("{\"kty\":\"RSA\",\"n\":\"0vx7...\",\"e\":\"AQAB\"}") 
= "-----BEGIN PUBLIC KEY----- MIIBIjANBgkqh... -----END PUBLIC KEY-----"

Пример 2: Использование для верификации JWT

FROMJWT({user:jwt}; FROMJWK({global:jwk_key}))

Примеры составных функций

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

Пример 1: Простая проверка длины имени и приветствие (начальный уровень)

Задача: Если имя пользователя длиннее 5 символов, поприветствовать его полным именем, иначе – кратко.

Формула:

ЕСЛИ(ДЛСТР({user:first_name}) > 5; "Привет, " & {user:first_name} & "!"; "Привет!")

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

Если {user:first_name} = "Артём": "Привет!"
Если {user:first_name} = "Александр": "Привет, Александр!"

Пример 2: Расчёт стоимости заказа со скидкой и округлением (средний уровень)

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

Предполагаемые параметры:

{user:количество_товаров}: "3"
{googlesheets:123:B2}: "15.50" (цена за единицу) - подстановка из google таблицы
{user:скидка_сумма}: "10"

Формула:

ОКРУГЛ(({user:количество_товаров} * {googlesheets:123:B2}) - {user:скидка_сумма}; 2)

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

Расчёт: (3 * 15.50) - 10 = 46.50 - 10 = 36.50
Округление: ОКРУГЛ(36.50; 2) = 36.50
Если googlesheets:123:B2 = "15.333", то ОКРУГЛ( (3 * 15.333) - 10; 2) = 36.00

Пример 3: Форматирование текущей даты и времени для отчёта (средний уровень)

Задача: Получить текущую дату и время, отформатировать их в виде "День недели, DD месяц YYYY года, HH:MM" и добавить 3 дня.

Предполагаемый параметр:

{user:date_time} = "12.06.2025 22:24:20"

Формула:

DATEFORMAT(DATEADD(DATEVALUE({user:date_time}); "P3D"); "l, d F Y года, H:i"; "ru")

Пример использования:

Итоговый вывод: "Воскресенье, 15 июня 2025 года, 22:24"

Пример 4: Обработка JSON-ответа и условный вывод (сложный уровень)

Задача: Из JSON-ответа получить список продуктов, затем отфильтровать только те, у которых статус "доступен", объединить их через запятую и вывести сообщение, или указать, что продуктов нет.

Предполагаемый параметр:

{user:api_response}:

{
  "products": [
    {"id": 1, "name": "Молоко", "status": "доступен"},
    {"id": 2, "name": "Хлеб", "status": "нет в наличии"},
    {"id": 3, "name": "Масло", "status": "доступен"}
  ]
}

Формула:

ЕСЛИ(ДЛСТР(
    JOIN(", "; ARRAYREMOVE(UNIQUE(FOREACH(
        JP({user:api_response}; "$.products"); 
        LAMBDA(product; ЕСЛИ(JP(product; "$.status") = "доступен"; JP(product; "$.name"); ""))));LAMBDA(val; key; val="")))) > 0;
"Доступные товары: " & 
    JOIN(", "; ARRAYREMOVE(UNIQUE(FOREACH(
        JP({user:api_response}; "$.products"); 
        LAMBDA(product; ЕСЛИ(JP(product; "$.status") = "доступен"; JP(product; "$.name"); ""))));LAMBDA(val; key; val="")));
"Нет доступных товаров.")

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

Если {user:api_response} содержит данные выше, то запишется в параметр: "Доступные товары: Молоко, Масло"
Если {user:api_response} содержит: {"products": [{"id": 1, "name": "Молоко", "status": "нет в наличии"}]} , то запишется в параметр:"Нет доступных товаров."

Краткий разбор формулы

Эта формула предназначена для извлечения названий "доступных" продуктов из JSON-ответа API, сохранённого в параметр {user:api_response} и формирования сообщения для пользователя. Если такие продукты найдены, она выводит их список; в противном случае — сообщает об их отсутствии.

Порядок выполнения формулы слева направо (от внутреннего к внешнему):

JP(..., "$.products"): Используя синтаксис JSONPath, извлекает массив (список) всех продуктов из полученного JSON-объекта.
FOREACH(..., LAMBDA(product; ЕСЛИ(JP(product; "$.status") = "доступен"; JP(product; "$.name"); ""))):
- Эта функция проходит по каждому product (объекту продукта) в извлеченном массиве.
- Внутри LAMBDA, ЕСЛИ(...) проверяет: если значение status продукта равно "доступен", то возвращается его name (имя).
- В противном случае (если статус не "доступен"), возвращается пустая строка "".
- Результатом этой части будет новый массив, содержащий имена доступных продуктов и пустые строки для недоступных. Например: ["Молоко", "", "Масло"].
UNIQUE(...): Удаляет любые повторяющиеся элементы из массива. В данном сценарии это может быть избыточно, но является хорошей практикой для обработки списков.
ARRAYREMOVE(..., LAMBDA(val; val="")): Удаляет все пустые строки ("") из массива, которые были добавлены для недоступных продуктов на шаге 3. Это очищает список, оставляя только имена доступных товаров.
JOIN(", "; ...): Объединяет оставшиеся элементы массива (имена доступных товаров) в одну строку, разделяя их запятой и пробелом. Например: "Молоко, Масло".
ДЛСТР(...): Вычисляет длину полученной строки с именами доступных товаров.
ЕСЛИ(ДЛСТР(...) > 0; ...; ...):
- Это главное условие. Если длина строки доступных товаров больше нуля (то есть, есть хотя бы один доступный товар), то выполняется первая часть ЕСЛИ.
- Если истина: Формируется сообщение "Доступные товары: " и к нему добавляется список товаров, полученный на шаге 5.
- Если ложь: Выводится сообщение "Нет доступных товаров.".

Таким образом, формула эффективно фильтрует и форматирует информацию о продуктах из JSON-ответа для удобного отображения пользователю.

Математические операции

Сложение (+)

Вычитание (-)

Умножение (*)

Деление (/)

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

Объединение (&)

ДЛСТР (LEN)

Логические функции

ЕСЛИ (IF)

ЕЧИСЛО (ISNUMBER)

И (AND)

ИЛИ (OR)

Функции для чисел

МИН (MIN)

МАКС (MAX)

ОКРУГЛ (ROUND)

ПИ (PI)

СРЗНАЧ (AVERAGE)

СУММ (SUM)

RANDBETWEEN (СЛУЧМЕЖДУ)

Функции для поиска в тексте

НАЙТИ (FIND)

ПОИСК (SEARCH)

Функции для работы с JSON

TOJSON

FROMJSON

JSONPATH

JSONPATHSMART (JP)

Функции для работы с датами и временем

DATEVALUE

DATEADD

DATESUB

DATEDIF (РАЗНДАТ)

DATEFORMAT

Функции для сортировки и кодирования

SORT

RSORT

TOBASE64

FROMBASE64

Функции для работы с массивами (списками)

ARRAYFIND

ARRAYREMOVE

ARRAYADD

ARRAYREPLACE

FOREACH

Функции для работы со строками (регистр)

UPPER (ПРОПИСН)

LOWER (СТРОЧН)

UPPERFIRST (ПРОПИСНПЕРВ)

Функции для создания JSON-структур

JSONOBJECT

JSONARRAY

Вспомогательные функции

NL

Функции для работы с параметрами

PARAMID

PARAMREMOVE

PARAMREPLACE

HASH (ХЭШ)

FROMJWT

FROMJWK (ИЗ JWK В ПУБЛИЧНЫЙ КЛЮЧ)

Примеры составных функций

Пример 1: Простая проверка длины имени и приветствие (начальный уровень)

Пример 2: Расчёт стоимости заказа со скидкой и округлением (средний уровень)

Пример 3: Форматирование текущей даты и времени для отчёта (средний уровень)

Пример 4: Обработка JSON-ответа и условный вывод (сложный уровень)

Краткий разбор формулы

Сложение (`+`)

Вычитание (`-`)

Умножение (`*`)

Деление (`/`)

Объединение (`&`)