Свойства скрипта Google Apps Script: Что нужно знать?

Что такое свойства скрипта и зачем они нужны?

Свойства скрипта в Google Apps Script – это механизм для хранения небольших объемов данных, связанных со скриптом, пользователем или документом. Они позволяют сохранять информацию между запусками скрипта, что полезно для сохранения настроек, кэширования данных и поддержания состояния.

Саммари статьи

ChatGPT

Google AI

Grok

Perplexity

Области действия свойств: скрипт, пользователь, документ

Свойства скрипта имеют три области действия:

1. Script: Свойства, доступные всем пользователям, запускающим скрипт. Подходят для хранения общих настроек и конфигураций.
2. User: Свойства, специфичные для каждого пользователя. Полезны для хранения пользовательских настроек и предпочтений.
3. Document: Свойства, связанные с конкретным документом, в котором запущен скрипт. Удобны для хранения метаданных и специфичных параметров документа.

Сравнение свойств скрипта с другими способами хранения данных (например, ScriptDb, PropertiesService)

По сравнению с другими способами хранения данных, такими как ScriptDb (устаревший) или более продвинутыми решениями, как Cloud SQL или Firestore, свойства скрипта предназначены для небольших объемов данных. Они проще в использовании и идеально подходят для базовых задач, таких как хранение конфигурационных параметров или кэширование временных данных. Для больших объемов данных или сложных запросов лучше использовать базы данных.

Управление свойствами скрипта с помощью PropertiesService

Получение доступа к PropertiesService

Для работы со свойствами скрипта используется класс PropertiesService. Получить доступ к нему можно через его статический метод getScriptProperties(), getUserProperties(), или getDocumentProperties() в зависимости от нужной области действия:

// Для скрипта
const scriptProperties = PropertiesService.getScriptProperties();

// Для пользователя
const userProperties = PropertiesService.getUserProperties();

// Для документа
const documentProperties = PropertiesService.getDocumentProperties();

Методы PropertiesService: getProperty(), setProperty(), deleteProperty(), getProperties(), setProperties(), deleteAllProperties()

PropertiesService предоставляет следующие основные методы:

• getProperty(key: string): string | null: Получает значение свойства по ключу. Возвращает null, если свойство не найдено.
• setProperty(key: string, value: string): Properties: Устанавливает значение свойства по ключу. Возвращает объект Properties.
• deleteProperty(key: string): Properties: Удаляет свойство по ключу. Возвращает объект Properties.
• getProperties(): { [key: string]: string }: Получает все свойства в виде объекта JavaScript.
• setProperties(properties: { [key: string]: string }): Properties: Устанавливает несколько свойств одновременно.
• deleteAllProperties(): Properties: Удаляет все свойства.

Примеры использования методов PropertiesService для чтения, записи и удаления свойств

/**
 * @param {string} apiKey The API key to store.
 * @return {void}
 */
function setApiKey(apiKey) {
  const scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.setProperty('API_KEY', apiKey);
}

/**
 * @return {string|null} The stored API key or null if not found.
 */
function getApiKey() {
  const scriptProperties = PropertiesService.getScriptProperties();
  return scriptProperties.getProperty('API_KEY');
}

/**
 * @return {void}
 */
function deleteApiKey() {
  const scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.deleteProperty('API_KEY');
}

function storeMultipleValues() {
  const scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.setProperties({
    'CLIENT_ID': 'your_client_id',
    'CLIENT_SECRET': 'your_client_secret'
  });
}

function getAllProperties() {
  const scriptProperties = PropertiesService.getScriptProperties();
  const allProperties = scriptProperties.getProperties();
  Logger.log(allProperties);
}

Типы данных, хранимые в свойствах скрипта

Строки (String)

Свойства скрипта хранят данные в виде строк.

Числа (Number)

Для хранения чисел их нужно преобразовывать в строки и обратно:

function storeAndRetrieveNumber() {
  const scriptProperties = PropertiesService.getScriptProperties();
  const numberValue = 123.45;

  scriptProperties.setProperty('NUMBER_VALUE', String(numberValue));

  const retrievedString = scriptProperties.getProperty('NUMBER_VALUE');
  if (retrievedString) {
    const retrievedNumber = Number(retrievedString);
    Logger.log(retrievedNumber); // Output: 123.45
  }
}

Булевы значения (Boolean)

Аналогично, булевы значения также преобразуются в строки:

function storeAndRetrieveBoolean() {
  const scriptProperties = PropertiesService.getScriptProperties();
  const booleanValue = true;

  scriptProperties.setProperty('BOOLEAN_VALUE', String(booleanValue));

  const retrievedString = scriptProperties.getProperty('BOOLEAN_VALUE');
  if (retrievedString) {
    const retrievedBoolean = retrievedString === 'true';
    Logger.log(retrievedBoolean); // Output: true
  }
}

Преобразование объектов и массивов в строки для хранения

Для хранения объектов и массивов их необходимо сериализовать в строку, например, с помощью JSON.stringify():

function storeAndRetrieveObject() {
  const scriptProperties = PropertiesService.getScriptProperties();
  const myObject = { name: 'John', age: 30 };
  const jsonString = JSON.stringify(myObject);

  scriptProperties.setProperty('OBJECT_VALUE', jsonString);

  const retrievedString = scriptProperties.getProperty('OBJECT_VALUE');
  if (retrievedString) {
    const retrievedObject = JSON.parse(retrievedString);
    Logger.log(retrievedObject); // Output: {name=John, age=30.0}
  }
}

Практическое применение свойств скрипта

Хранение конфигурационных параметров скрипта

Например, можно хранить URL API, ключи API, параметры подключения к базе данных и другие настройки:

function setApiConfig(apiUrl, apiKey) {
  const scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.setProperties({
    'API_URL': apiUrl,
    'API_KEY': apiKey
  });
}

Кэширование данных для повышения производительности

Можно кэшировать результаты вызовов API или сложных вычислений:

function getCachedData(key, fetchFunction) {
  const scriptProperties = PropertiesService.getScriptProperties();
  let cachedData = scriptProperties.getProperty(key);

  if (!cachedData) {
    const data = fetchFunction();
    cachedData = JSON.stringify(data);
    scriptProperties.setProperty(key, cachedData);
  }

  return JSON.parse(cachedData);
}

Сохранение состояния скрипта между выполнениями

Например, можно хранить текущий индекс обработки данных или последний обработанный элемент:

function setLastProcessedIndex(index) {
  const scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.setProperty('LAST_PROCESSED_INDEX', String(index));
}

function getLastProcessedIndex() {
  const scriptProperties = PropertiesService.getScriptProperties();
  const indexString = scriptProperties.getProperty('LAST_PROCESSED_INDEX');
  return indexString ? Number(indexString) : 0;
}

Использование свойств скрипта для реализации пользовательских настроек

Можно хранить предпочитаемый язык, тему оформления и другие пользовательские параметры:

function setUserPreference(userEmail, preferenceKey, preferenceValue) {
  const userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty(userEmail + '_' + preferenceKey, preferenceValue);
}

function getUserPreference(userEmail, preferenceKey) {
  const userProperties = PropertiesService.getUserProperties();
  return userProperties.getProperty(userEmail + '_' + preferenceKey);
}

Ограничения и лучшие практики при работе со свойствами скрипта

Ограничения по размеру свойств и общему объему хранилища

Существуют ограничения на размер отдельных свойств (до 9 КБ) и общий объем хранилища (до 500 КБ для скриптов и документов). Превышение этих лимитов приведет к ошибкам.

Вопросы безопасности и конфиденциальности данных

Не храните конфиденциальные данные, такие как пароли или номера кредитных карт, в свойствах скрипта. Рассмотрите возможность использования Secret Manager, если требуется хранить секреты.

Рекомендации по организации и именованию свойств

Используйте осмысленные имена свойств, чтобы облегчить понимание их назначения. Организуйте свойства по логическим группам, чтобы упростить управление.

Альтернативные подходы при превышении лимитов свойств

Если вы превышаете лимиты свойств, рассмотрите возможность использования баз данных (например, Cloud SQL, Firestore) или внешних сервисов для хранения данных.