Переменные сервиса
Создание переменных, заполнение значений, автосохранение и доступ сотрудников.
Переменные хранят настройки конкретного сервиса в компании: например, адрес подключения или параметры отчёта. Значения общие для всех сотрудников, которые работают с этим сервисом.
Настройка и права доступа
В Администратор → Сервисы откройте сохранённый встроенный сервис и вкладку Переменные после предпросмотра. Нажмите Создать переменную, задайте имя латиницей и выберите Текст, Число, Да / нет или 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-шаблон исходников пока не содержит определений переменных — их перенос через магазин выполняется отдельным серверным форматом пакета.