Синтаксис

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

Переход на новую версию синтаксиса

Новая версия синтаксиса имеет более широкий список функций, чем старая, и позволяет реализовывать большее количество сценариев, например:

1. Работа с циклами;

2. Парсинг объектов объектов неизвестной структуры и массивов переменной длины;

3. Применение большого количества фильтров к данным.

В настоящее время все новые агенты создаются в новой версии синтаксиса. Перейти со старой на новую версию можно следующим образом:

1. Поменять версию в конфигурационном файле Агента — заменить “1” на “2”, затем создать Агента путем импорта файла в Платформе либо замены конфигурационного файла.

Важно: Сценарий может быть либо 1-й версии, либо 2-й. Одновременно использовать обе версии синтаксиса в Сценария нельзя.

Изменения после перехода на новую версию синтаксиса

В результате процедуры апгрейда с агентом произойдут следующие изменения:

1. Если переход был совершен с помощью кнопки UPGRADE на карточке Агента или в БотБилдере (способ более не доступен), в БотБилдере будут подсвечены те Слоты, в которых используются конструкции старой версии синтаксиса.

   1. Внутри этих Слотов отображаются предупреждения о том, что Слот содержит старый синтаксис, и что необходимо его отредактировать вручную — переписать выражения с использованием конструкций нового синтаксиса.
   2. После того как проблемный Слот отредактирован, предупреждение можно убрать, нажав SLOT FIXED, REMOVE ALERT.

2. При попытке обучить Агента, не отредактировав проблемные Слоты, появится ошибка Валидация сценария. В тексте уведомления будут указаны id Слотов, ошибки и выражения, в которых допущены ошибки.
3. После перехода на 2-ую версию синтаксиса вернуться к 1-ой версии можно, поменяв версию в конфигурационном файле Агента.

Общая информация о новой версии синтаксиса

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

• Text: допустимо использование Выражений и Управляющих конструкций в поле Text List

• Attachment: допустимо использование Выражений и Управляющих конструкций в полях Source и Caption

• Slot Filling: допустимо использование Выражений и Управляющих конструкций в поле Question

• button: допустимо использование Выражений в поле Label

• condition: допустимо использование Выражений в поле Condition

• Timer: допустимо использование Выражений в поле If

• Memory: допустимо использование Выражений и Управляющих конструкций в поле Value

• External Request: допустимо использование Выражений и Управляющих конструкций в полях URL, Value на вкладке Headers и Query parameters, Data, поле Name на вкладке Response

• Incoming Request: допустимо использование Выражений и Управляющих конструкций в поле Value

• Synonim: допустимо использование Выражений и Управляющих конструкций в поле Source

Новая версия использует синтаксис шаблонизатора Jinja: https://jinja.palletsprojects.com/en/3.0.x/templates/

Шаблоны в синтаксисе делятся на 2 концепции:

1. Выражение. Заключаются в двойные фигурные скобки.

   https://jinja.palletsprojects.com/en/3.0.x/templates/#expressions

   Примеры:

   1. {{ client_message }}

   2. {{ number * 10 }}

   3. {{ chat_id == ‘abcde0123456789’ }}

   4. {{ uuid4() }}

   5. {{ some_variable is defined }}

2. Управляющая конструкция. Заключаются в фигурные скобки с символом %. https://jinja.palletsprojects.com/en/3.0.x/templates/#list-of-control-structures

   Примеры:

   1. {% if client_message == ‘привет’ %}Hi{% else %}Bye{% endif %}

   2. {% for number in [1, 2, 3] %}{{ number }}{% endfor %}

Выражения

Литералы

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

Ограничения:

• Максимальное число (по модулю), которое можно использовать в арифметических операциях — 4294967296. Если использовать большие числа, то будет ошибка (в memory в переменную сохранится False, например).

• Если складывать строки / массивы, то максимально допустимая длина строки / массива — 1000.

Операции сравнения

Логические операции

Другие операции

Проверки значений переменных

Фильтры синтаксиса

If-выражения

Оператор	Тип	Обозначение	Область применения	Как использовать	Пример
Условные конструкции	if-выражения	if, elif, else	Любые контекстные переменные	Простые условные конструкции, например, для слота Memory:{{ <do something> if <something is true> else <do something else> }}Могут использоваться elif и else.Часть с else необязательна: при ее отсутствии, если условие if <something is true> не выполняется, результатом станет ‘False’.	{{ 42 if client_message == "Привет" else 111 }} Результат: ‘42’, если переменная client_message содержит значение "Привет";‘111’, если переменная client_message содержит любое другое значение. {{ 42 if client_message == "Привет"}} Результат: ‘42’, если переменная client_message содержит значение "Привет";‘False’, если переменная client_message содержит любое другое значение.

Управляющие конструкции

For

Оператор	Тип	Обозначение	Область применения	Как использовать	Пример
Пройти циклом по каждому элементу последовательности	For	for, in, endfor	Любые контекстные переменные	{% for A in B %}{{ ... }}{% endfor %}Важно: цикл может быть максимум двойной вложенности.Внутри циклов можно использовать дополнительные переменные для проверки значений: Проверки значений переменных внутри For-циклов	{% for number in [1, 2, 3] %}{{ number }}{% endfor %}Результат: 123.

Проверки значений переменных внутри For-циклов

If

Оператор	Тип	Обозначение	Область применения	Как использовать	Пример
Условные конструкции	If	if, elif, else, endif	Любые контекстные переменные	Для более больших условий, нежели if-выражения, например, для слота Text:{% if ... %}A{% else %}B{% endif %}Могут использоваться elif и else.	{% if current_time > 18 %} Добрый вечер! {% else %} Добрый день! {% endif %} Результат: ‘Добрый вечер!’, если переменная current_time содержит значение более 18.‘Добрый день!’, если переменная current_time содержит значение менее либо равное 18.

Filters

Оператор	Тип	Обозначение	Область применения	Как использовать	Пример
Применяет фильтр по отношению к блоку данных шаблона	Filters	filter, endfilter	Любые контекстные переменные	Аналогично выражениям с использованием фильтров, только для более больших условий{% filter <фильтр> %} TEXT{% endfilter %}Фильтры: Фильтры синтаксиса	{% filter upper %} This text becomes uppercase {% endfilter %} Результат: THIS TEXT BECOMES UPPERCASE.

Assignments

Оператор	Тип	Обозначение	Область применения	Как использовать	Пример
Присваивает значение операнду	Assignments	set	Любые контекстные переменные	{% set A = B%}	{% set x = 'apples' if age is even else 'oranges' %}{{ x }} Результат: ‘apples’, если переменная age содержит четное число.‘oranges’, если переменная age содержит нечетное число.

Ошибки при рендеринге Шаблонов

При Обучении агента в процессе Валидация сценария проверяется правильность используемых в Слотах Выражение и Управляющая конструкция. При обнаружении ошибок появится предупреждение:

Формат текста предупреждения:

Invalid template syntax: Slot <id проблемного слота>. Error "<описание ошибки>" in expression "<проблемное выражение>"

Пример:

Invalid template syntax: Slot 8848840. Error “unexpected char '@' at 3” in expression “{{ @foo }}”

Расшифровка ошибки: в Слоте 8848840 обнаружена ошибка — лишний символ '@' с порядковым номером 3 в выражении {{ @foo }}. Важно: отсчет порядковых номеров символов в проблемном выражении начинается с 0.