Что такое Properties Service и зачем он нужен?
Properties Service в Google Apps Script – это простой механизм для хранения небольших объемов данных в виде пар ключ-значение. Он позволяет сохранять информацию, которая должна быть доступна между различными выполнениями скрипта или для разных пользователей. Представьте себе его как небольшой, встроенный в Google Workspace сервис для хранения конфигурационных данных или пользовательских настроек. Он полезен, когда не требуется полноценная база данных, а нужно просто сохранить несколько параметров.
Основные области применения Properties Service
Properties Service часто используют для:
Сохранения настроек пользователя (например, предпочитаемый язык интерфейса).
Сохранения состояния скрипта между запусками (например, последний обработанный ID записи).
Кэширования часто используемых данных (например, результатов запросов к внешним API).
Хранения параметров конфигурации скрипта (например, ключи API).
В контексте интернет-маркетинга это может быть, например, хранение API ключей рекламных платформ или ID рекламных кампаний, которые нужно обрабатывать скриптом. В web-программировании, можно хранить настройки доступа к внешним сервисам или состояние сессии пользователя.
Отличия Properties Service от других способов хранения данных
В отличие от Cache Service, данные в Properties Service хранятся постоянно (до тех пор, пока их не удалят), в то время как данные в Cache Service имеют срок жизни. В отличие от полноценных баз данных (например, Google Cloud SQL), Properties Service предназначен для хранения небольших объемов данных и не поддерживает сложные запросы. Основное преимущество Properties Service – простота использования и интеграция с Google Apps Script.
Области действия свойств (Scopes)
Properties Service предоставляет несколько областей действия (scopes) для хранения данных, определяющих, кто имеет доступ к этим данным:
User Properties: свойства, специфичные для пользователя
User Properties доступны только тому пользователю, который выполняет скрипт. Это подходит для хранения пользовательских настроек, которые должны быть уникальными для каждого пользователя.
Script Properties: свойства, специфичные для скрипта
Script Properties доступны всем пользователям, имеющим доступ к скрипту (редакторам и тем, кто имеет разрешение на выполнение). Это полезно для хранения параметров конфигурации скрипта, которые одинаковы для всех пользователей.
Document Properties: свойства, специфичные для документа (только для контейнерных скриптов)
Document Properties доступны только для скриптов, привязанных к определенному документу (например, Google Sheets или Google Docs). Они доступны всем пользователям, имеющим доступ к этому документу. Это подходит для хранения данных, специфичных для конкретного документа.
Когда какую область действия использовать?
User Properties: для настроек, которые пользователь может менять и которые должны быть уникальны для каждого пользователя.
Script Properties: для параметров, которые контролируются разработчиком и влияют на работу скрипта в целом.
Document Properties: для данных, связанных с конкретным документом, и к которым должны иметь доступ все, кто имеет доступ к документу.
Методы работы с Properties Service
Получение доступа к Properties Service (getProperties, getUserProperties, getScriptProperties, getDocumentProperties)
Для начала работы с Properties Service необходимо получить доступ к нужному типу свойств:
/**
* Получает доступ к Script Properties.
*
* @return {Properties} Объект Properties для Script Properties.
*/
function getScriptPropertiesObject() {
return PropertiesService.getScriptProperties();
}
/**
* Получает доступ к User Properties.
*
* @return {Properties} Объект Properties для User Properties.
*/
function getUserPropertiesObject() {
return PropertiesService.getUserProperties();
}Для Document Properties (только для контейнерных скриптов):
/**
* Получает доступ к Document Properties для Google Sheets.
*
* @return {Properties} Объект Properties для Document Properties.
*/
function getDocumentPropertiesObject() {
// Предполагается, что скрипт привязан к Google Sheets
return PropertiesService.getDocumentProperties();
}Сохранение данных (setProperty, setProperties)
Для сохранения данных используются методы setProperty и setProperties:
/**
* Сохраняет одно свойство в Script Properties.
*
* @param {string} key Ключ свойства.
* @param {string} value Значение свойства.
*/
function saveScriptProperty(key: string, value: string) {
const scriptProperties = getScriptPropertiesObject();
scriptProperties.setProperty(key, value);
}
/**
* Сохраняет несколько свойств в User Properties.
*
* @param {object} properties Объект с парами ключ-значение для сохранения.
*/
function saveUserProperties(properties: object) {
const userProperties = getUserPropertiesObject();
userProperties.setProperties(properties);
}Получение данных (getProperty, getProperties)
Для получения данных используются методы getProperty и getProperties:
/**
* Получает значение свойства из Script Properties.
*
* @param {string} key Ключ свойства.
* @return {string|null} Значение свойства или null, если свойство не найдено.
*/
function getScriptProperty(key: string): string | null {
const scriptProperties = getScriptPropertiesObject();
return scriptProperties.getProperty(key);
}
/**
* Получает все свойства из User Properties.
*
* @return {object} Объект со всеми User Properties.
*/
function getAllUserProperties(): object {
const userProperties = getUserPropertiesObject();
return userProperties.getProperties();
}Удаление данных (deleteProperty, deleteAllProperties)
Для удаления данных используются методы deleteProperty и deleteAllProperties:
/**
* Удаляет свойство из Script Properties.
*
* @param {string} key Ключ свойства для удаления.
*/
function deleteScriptProperty(key: string) {
const scriptProperties = getScriptPropertiesObject();
scriptProperties.deleteProperty(key);
}
/**
* Удаляет все свойства из User Properties.
*/
function deleteAllUserProperties() {
const userProperties = getUserPropertiesObject();
userProperties.deleteAllProperties();
}Примеры использования Properties Service
Сохранение настроек пользователя
Предположим, что скрипт отправляет email-уведомления и пользователь может выбрать частоту отправки (ежедневно, еженедельно, ежемесячно). Эту настройку можно сохранить в User Properties.
function setUserNotificationFrequency(frequency: string) {
const userProperties = PropertiesService.getUserProperties();
userProperties.setProperty('notificationFrequency', frequency);
}
function getUserNotificationFrequency(): string | null {
const userProperties = PropertiesService.getUserProperties();
return userProperties.getProperty('notificationFrequency');
}Сохранение состояния скрипта между запусками
Например, скрипт обрабатывает данные из Google Sheets построчно и нужно сохранить номер последней обработанной строки.
function setLastProcessedRow(row: number) {
const scriptProperties = PropertiesService.getScriptProperties();
scriptProperties.setProperty('lastProcessedRow', String(row));
}
function getLastProcessedRow(): number {
const scriptProperties = PropertiesService.getScriptProperties();
const row = scriptProperties.getProperty('lastProcessedRow');
return row ? parseInt(row) : 1; // Начинаем с первой строки, если ничего не сохранено
}Кэширование часто используемых данных
Если скрипт часто обращается к внешнему API за данными, можно кэшировать результаты в Script Properties.
function getCachedData(key: string, fetchFunction: Function, expirySeconds: number = 3600) {
const scriptProperties = PropertiesService.getScriptProperties();
let cachedData = scriptProperties.getProperty(key);
if (!cachedData) {
const data = fetchFunction();
scriptProperties.setProperty(key, JSON.stringify(data));
//TODO: Add code to remove old cache after some time (expirySeconds)
return data;
}
return JSON.parse(cachedData);
}Пример работы с Document Properties в Google Sheets
Предположим, что в Google Sheets есть скрипт, который отправляет email-уведомления на основе данных из таблицы. Можно сохранить адрес отправителя в Document Properties, чтобы любой, у кого есть доступ к таблице, мог его изменить.
function setSenderEmail(email: string) {
const documentProperties = PropertiesService.getDocumentProperties();
documentProperties.setProperty('senderEmail', email);
}
function getSenderEmail(): string | null {
const documentProperties = PropertiesService.getDocumentProperties();
return documentProperties.getProperty('senderEmail');
}Ограничения и лучшие практики
Ограничения по размеру и количеству свойств
Properties Service имеет ограничения по размеру каждого свойства (9KB) и общему объему хранилища для каждого скрипта или пользователя. Важно следить за размером сохраняемых данных, чтобы не превысить лимиты. С актуальными лимитами можно ознакомиться в документации Google Apps Script.
Безопасность хранения данных
Properties Service не предназначен для хранения конфиденциальных данных, таких как пароли или номера кредитных карт. Данные хранятся в незашифрованном виде. Для хранения чувствительной информации следует использовать более безопасные решения.
Оптимизация производительности при работе с Properties Service
Чтение и запись свойств – относительно медленные операции. Старайтесь минимизировать количество обращений к Properties Service, особенно в циклах. Используйте getProperties и setProperties для работы с несколькими свойствами за один раз.
Альтернативы Properties Service: Cache Service и базы данных
Если нужно хранить большие объемы данных или требуется сложная логика запросов, лучше использовать полноценную базу данных, такую как Google Cloud SQL или Firestore. Если данные нужны только на короткий срок, можно использовать Cache Service.