Synchra.24
menu_bookDocumentation
Practical guides for setup and development

Find guides for getting started, building workflows and adding your own tools to your company workspace.

folderEmbedded services

Service variables

Creating variables, filling in values, auto-save, and employee access.

Translation is currently unavailable. The original is shown.

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

Настройка и права доступа

В Администратор → Сервисы откройте сохранённый встроенный сервис и вкладку Переменные после предпросмотра. Нажмите Создать переменную, задайте имя латиницей и выберите Текст, Число, Да / нет или JSON. Имя начинается с буквы, содержит до 64 символов: буквы, цифры, _, . или -. Описание необязательно, до 500 символов. Переключатель Задать значение позволяет сохранить определение незаполненным; его выключение при редактировании очищает прежнее значение. Имя созданной переменной не меняется. Тип можно изменить вместе с новым подходящим значением либо после очистки.

Значение редактируется прямо в строке списка, без открытия отдельного окна. Для текста и числа используется поле, для значения «Да / нет» — список выбора, для JSON — текстовая область, которую можно увеличить. Значение сохраняется автоматически после короткой паузы; выход из текстового поля сохраняет его сразу. Кнопка очистки убирает содержимое, сохраняя само определение. Ошибка проверки или сервера показывается рядом с полем, введённые данные остаются на экране.

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

Если значение не сохраняется

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

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

Использование в коде сервиса

Чтение синхронное, без await и без запроса на сервер при каждом обращении:

const apiToken = synchra.getVariable('api_token');
const settings = synchra.getVariable('settings'); // JSON тоже возвращается сразу
const info = synchra.getVariableInfo('settings'); // is_set, revision, type и другие поля

await synchra.setVariable('settings', { enabled: true }, { revision: info.revision });
const updated = synchra.getVariable('settings'); // уже обновлённое локальное значение

getVariable() возвращает непосредственно значение; для незаполненной переменной — undefined. Заданный JSON null возвращается как null. Неизвестное имя вызывает ошибку. Объекты возвращаются копиями: изменение объекта само по себе ничего не сохраняет. Для записи используйте асинхронный setVariable(); при успешном ответе локальный снимок обновляется. При ошибке записи он не меняется. Необязательная ревизия защищает от перезаписи чужого изменения (ошибка 409).

Снимок загружается при открытии сервиса; изменения из других открытых экземпляров появляются при следующем открытии. В предпросмотре запись меняет только локальные тестовые данные, без сохранения в компании. Допускается до 100 переменных на сервис, до 64 КиБ JSON на значение. Значения доступны исполняемому коду и сотрудникам с доступом к сервису: не храните здесь секреты, которые нельзя раскрывать этим сотрудникам.

Переменные в магазине расширений

При публикации встроенного сервиса или пакета магазин получает определения переменных, но не их значения: только имя, тип и описание. Покупателю создаются пустые переменные, которые он заполняет в настройках установленного сервиса. Перед первым запуском объясните обязательные значения в описании продукта; проверяйте незаполненные настройки через getVariable() или getVariableInfo() и показывайте пользователю понятное сообщение.

Обновление установленного продукта добавляет новые определения, сохраняя уже созданные определения и значения покупателя. Смена типа у продавца не перезаписывает существующее определение у покупателя; планируйте совместимость версий кода. Повторная установка той же версии не обнуляет данные. Локальный ZIP-шаблон исходников пока не содержит определений переменных — их перенос через магазин выполняется отдельным серверным форматом пакета.