Что такое Свойства Пользователя (User Properties)?
Свойства пользователя (User Properties) в Google Apps Script – это простой механизм для хранения данных, специфичных для каждого пользователя скрипта. По сути, это хранилище ключ-значение, где ключ – это строка, идентифицирующая свойство, а значение – произвольная строка, связанная с этим ключом. Каждый пользователь, работающий со скриптом, имеет свое собственное, изолированное хранилище User Properties.
Для чего нужны Свойства Пользователя: примеры использования
User Properties полезны для:
Сохранения пользовательских настроек скрипта (например, язык интерфейса, тема оформления).
Запоминания последнего состояния приложения для каждого пользователя (например, последняя открытая вкладка, фильтры данных).
Реализации простых механизмов авторизации (например, сохранение логина пользователя для автоматического входа, но не пароля!).
Кэширования промежуточных результатов вычислений для ускорения работы скрипта (особенно актуально для ресурсоемких операций).
В контексте интернет-маркетинга, User Properties можно использовать для хранения ID рекламных аккаунтов пользователя, настроек отчетов, или сохраненных фильтров в дашбордах, созданных на основе данных из Google Analytics или Google Ads.
Отличия от Свойств Документа и Скрипта
Важно понимать разницу между User Properties, Document Properties и Script Properties:
User Properties: Данные хранятся для каждого пользователя скрипта отдельно.
Document Properties: Данные хранятся для конкретного документа Google Docs, Sheets или Slides, к которому привязан скрипт. Доступны всем, у кого есть доступ к документу.
Script Properties: Данные хранятся для всего скрипта и доступны всем пользователям, запускающим скрипт.
User Properties обеспечивают персонализацию и изолированность данных, в то время как Document и Script Properties позволяют хранить общие настройки и данные.
Управление Свойствами Пользователя в Google Apps Script
Получение доступа к сервису UserProperties
Для работы с User Properties необходимо получить доступ к соответствующему сервису. Это делается следующим образом:
/**
* Получает сервис UserProperties.
* @return {GoogleAppsScript.Properties.Properties}
*/
function getUserPropertiesService() {
return PropertiesService.getUserProperties();
}
const userProperties = getUserPropertiesService();Сохранение данных: методы setProperty() и setProperties()
Для сохранения данных используются методы setProperty() и setProperties():
/**
* Сохраняет одно свойство пользователя.
* @param {string} key Ключ свойства.
* @param {string} value Значение свойства.
*/
function saveUserProperty(key: string, value: string) {
userProperties.setProperty(key, value);
}
/**
* Сохраняет несколько свойств пользователя.
* @param {object} properties Объект, где ключи - имена свойств, а значения - их значения.
*/
function saveUserProperties(properties: object) {
userProperties.setProperties(properties);
}
// Пример использования
saveUserProperty('language', 'ru');
saveUserProperties({ theme: 'dark', ads_account_id: '1234567890' });Извлечение данных: метод getProperty()
Для получения значения свойства используется метод getProperty():
/**
* Получает значение свойства пользователя.
* @param {string} key Ключ свойства.
* @return {string|null} Значение свойства, или null, если свойство не найдено.
*/
function getUserProperty(key: string): string | null {
return userProperties.getProperty(key);
}
// Пример использования
const language = getUserProperty('language');
if (language) {
Logger.log('Язык пользователя: ' + language);
}Удаление данных: метод deleteProperty()
Для удаления свойства используется метод deleteProperty():
/**
* Удаляет свойство пользователя.
* @param {string} key Ключ свойства.
*/
function deleteUserProperty(key: string) {
userProperties.deleteProperty(key);
}
// Пример использования
deleteUserProperty('theme');Практические примеры использования Свойств Пользователя
Сохранение пользовательских настроек скрипта
Предположим, у нас есть скрипт для анализа данных контекстной рекламы. Пользователь может выбрать валюту отображения данных. Можно сохранить выбранную валюту в User Properties:
/**
* Сохраняет валюту пользователя.
* @param {string} currency Валюта пользователя.
*/
function setUserCurrency(currency: string) {
saveUserProperty('currency', currency);
}
/**
* Получает валюту пользователя.
* @return {string} Валюта пользователя.
*/
function getUserCurrency(): string {
const currency = getUserProperty('currency');
return currency || 'USD'; // Значение по умолчанию
}Запоминание последнего состояния приложения для пользователя
Для веб-приложения на Google Apps Script можно запоминать, какую вкладку пользователь просматривал последней. При следующем открытии приложения, автоматически открывать эту вкладку. Это значительно улучшает UX.
/**
* Сохраняет последнюю открытую вкладку.
* @param {string} tabName Название вкладки.
*/
function setLastActiveTab(tabName: string) {
saveUserProperty('lastActiveTab', tabName);
}
/**
* Получает последнюю открытую вкладку.
* @return {string} Название вкладки.
*/
function getLastActiveTab(): string {
return getUserProperty('lastActiveTab') || 'dashboard'; // Значение по умолчанию
}Реализация простой системы авторизации (не для критически важных данных)
Не рекомендуется использовать User Properties для хранения конфиденциальной информации, такой как пароли. Однако, для простых сценариев, например, для запоминания имени пользователя, можно использовать User Properties.
/**
* Сохраняет имя пользователя.
* @param {string} username Имя пользователя.
*/
function setUsername(username: string) {
saveUserProperty('username', username);
}
/**
* Получает имя пользователя.
* @return {string} Имя пользователя.
*/
function getUsername(): string {
return getUserProperty('username') || '';
}Ограничения и Рекомендации по использованию Свойств Пользователя
Ограничения по размеру и количеству хранимых данных
Существуют ограничения на размер одного свойства и общее количество свойств на пользователя. Перед использованием User Properties рекомендуется ознакомиться с официальной документацией Google Apps Script для получения актуальной информации об этих лимитах.
Соображения безопасности: что не следует хранить в User Properties
Категорически не рекомендуется хранить в User Properties конфиденциальные данные, такие как пароли, номера кредитных карт, или другую персональную информацию, требующую повышенной защиты. User Properties не предназначены для хранения чувствительной информации.
Альтернативы Свойствам Пользователя для более сложных сценариев
Для более сложных сценариев, требующих хранения больших объемов данных или обеспечения повышенной безопасности, следует использовать другие решения, такие как:
Google Cloud Datastore/Firestore: Надежные и масштабируемые NoSQL базы данных.
Google Sheets: Для хранения и обработки табличных данных.
Внешние базы данных: MySQL, PostgreSQL и другие.
Заключение
Преимущества использования Свойств Пользователя
User Properties – это удобный и простой способ хранения данных, специфичных для каждого пользователя скрипта. Они позволяют персонализировать работу скрипта, запоминать пользовательские настройки и состояние приложения. Простота использования делает их отличным выбором для небольших проектов и прототипирования.
Дальнейшее изучение возможностей Google Apps Script
Google Apps Script предоставляет широкий спектр возможностей для автоматизации задач и интеграции с различными сервисами Google. Для дальнейшего изучения рекомендуется ознакомиться с официальной документацией и примерами кода, доступными на сайте Google Developers.