SetVarCloud

SetVarCloud — создаёт или полностью заменяет значение облачной переменной.

📝 Назначение

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

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

⚙️ Параметры

Параметр	Тип	Обязательный	Описание
Тип переменной	Выбор	✅ Да	`person`, `member`, `chat`, `global`, `dynamic`
Название	Строка	✅ Да	Имя переменной (только латиница, цифры, нижнее подчеркивание). Максимум 64 символа
Значение	Разный	❌ Нет	Значение для сохранения. Можно оставить пустым — получится нулевое значение
ID пользователя	Integer	❌ Нет	Для типа `person`. По умолчанию — текущий пользователь
ID чата	Integer	❌ Нет	Для типов `member` и `chat`. По умолчанию — текущий чат

📍 Подсказка: Тип данных здесь не выбирается — он задан в настройках самой облачной переменной при её создании в админке. Значение должно соответствовать этому типу.

📊 Поддерживаемые типы значений

Тип переменной	Пример значения	Формат
Логическое	`true`, `false`, `1`, `0`	`bool`
Целое число	`42`	`number`
Дробное число	`10.5`	`float`
Строка	`Москва`	`string`
Объект	`{"city": "Msk", "age": 25}`	`json` или `yaml`
Список	`["a", "b", "c"]`	`array json` / `array yaml`

⚠️ Важно: Если значение не соответствует типу переменной (например, abc для числовой), реакция завершится ошибкой и значение не сохранится.

🅾️ Пустое значение

Значение можно не указывать: при создании реакции есть кнопка «Пропустить», при редактировании — «Сбросить». Пустое значение превращается в нулевое значение того типа, который задан у переменной.

Тип переменной	Что будет сохранено
Логическое	`false`
Целое, дробное	`0`
Строка	Пустая строка
Объект	Пустой объект `{}`
Список	Пустой список `[]`

⚠️ Частая ошибка: Пустым считается и результат подстановки. Если в значении написано ${var.person.чего-нет}, подстановка даст пустоту, и переменная получит нулевое значение, а не ошибку. Для подстраховки указывайте запасное значение: ${var.person.count|default: 0}.

💡 Совет: Это не то же самое, что удаление. DelVarCloud убирает запись целиком, а пустое значение сохраняет переменную с нулевым значением.

🧪 Примеры

Пример 1: Сохранить имя пользователя

Где: В обработчике команды /start

Параметры SetVarCloud:

Тип: person
Название: saved_name
Значение: ${user.name}

Результат: В переменной ${var.person.saved_name} будет имя пользователя.

Пример 2: Сохранить числовое значение (баланс)

Где: После успешного пополнения счёта

Параметры SetVarCloud:

Тип: person
Название: balance
Значение: 1000

Результат: Переменная balance установлена в 1000. Старое значение (если было) утеряно.

Пример 3: Сохранить JSON-объект

Где: После заполнения формы заказа

Параметры SetVarCloud:

Тип: person
Название: order
Значение: {"id": 123, "sum": 1500, "items": ["товар1", "товар2"]}

Результат: Доступ к полям:

${var.person.order.id} → 123
${var.person.order.sum} → 1500
${var.person.order.items.0} → "товар1"

Пример 4: Сохранить значение для другого пользователя

Где: Администратор начисляет бонус пользователю с ID 987654321

Параметры SetVarCloud:

Тип: person
Название: bonus
Значение: 500
ID пользователя: 987654321

Результат: У пользователя 987654321 появилась переменная bonus со значением 500.

Пример 5: Сохранить значение в чате (групповая переменная)

Где: В группе установлен режим «тихий час»

Параметры SetVarCloud:

Тип: chat
Название: quiet_mode
Значение: true

Результат: Любой участник группы может проверить: !{varcloud|type: chat; name: quiet_mode} → true

🔄 Разница между SetVarCloud и AddVarCloud

Операция	SetVarCloud	AddVarCloud
Число `10` → `5`	✅ Будет `5`	❌ Будет `15` (прибавит)
Строка `"A"` → `"B"`	✅ Будет `"B"`	❌ Будет `"AB"` (добавит в конец)
Массив `[1,2]` → `[3,4]`	✅ Будет `[3,4]`	❌ Будет `[1,2,3,4]` (добавит элементы)
Объект `{"a":1}` → `{"b":2}`	✅ Будет `{"b":2}`	❌ Будет `{"a":1, "b":2}` (объединит)

💡 Совет: Используйте SetVarCloud для установки начального значения или полной замены. Используйте AddVarCloud для накопления (счётчики, списки).

🔗 Связанные реакции

GetVarCloud — загрузить значение переменной
AddVarCloud — изменить значение без полной замены
DelVarCloud — удалить переменную
Макрос varcloud — быстрый доступ без GetVarCloud

🔗 Связанные разделы

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