Servicio de propiedades

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

El Servicio de propiedades te permite almacenar datos simples en pares clave-valor con alcance a una secuencia de comandos, un usuario de una secuencia de comandos o un documento en el que se usa un complemento. Por lo general, se usa para almacenar la configuración del desarrollador o las preferencias del usuario. Las propiedades nunca se comparten entre las secuencias de comandos.

Si quieres ver las cuotas diarias y los límites de almacenamiento del servicio de Propiedades, consulta Cuotas para los servicios de Google.

Comparación de tiendas de propiedades

El objeto global PropertiesService ofrece tres métodos, cada uno de los cuales muestra un objeto Properties similar, pero con derechos de acceso diferentes, como se muestra en la siguiente tabla:

Propiedades de secuencia de comandos Propiedades del usuario Propiedades del documento
Método de acceso getScriptProperties() getUserProperties() getDocumentProperties()
Datos compartidos entre Todos los usuarios de una secuencia de comandos, un complemento o una aplicación web El usuario actual de una secuencia de comandos, un complemento o una aplicación web Todos los usuarios de un complemento en el documento abierto
Se suele usar para Datos de configuración de toda la app, como el nombre de usuario y la contraseña de la base de datos externa del desarrollador Configuración específica del usuario, como métricas o unidades imperiales Datos específicos del documento, como la URL de origen de un gráfico incorporado

Formato de los datos

El servicio de propiedades almacena todos los datos como strings en pares clave-valor. Los tipos de datos que aún no son strings se convierten automáticamente en strings, incluidos los métodos que se encuentran en los objetos guardados.

Cómo guardar datos

Para guardar un solo valor, llama al método Properties.setProperty(key, value) de la tienda correspondiente, como se muestra en el siguiente ejemplo:

service/propertyService.gs
try {
  // Set a property in each of the three property stores.
  const scriptProperties = PropertiesService.getScriptProperties();
  const userProperties = PropertiesService.getUserProperties();
  const documentProperties = PropertiesService.getDocumentProperties();

  scriptProperties.setProperty('SERVER_URL', 'http://www.example.com/');
  userProperties.setProperty('DISPLAY_UNITS', 'metric');
  documentProperties.setProperty('SOURCE_DATA_ID',
      '1j3GgabZvXUF177W0Zs_2v--H6SPCQb4pmZ6HsTZYT5k');
} catch (err) {
  // TODO (developer) - Handle exception
  Logger.log('Failed with error %s', err.message);
}

Para guardar datos de forma masiva, pasa un mapa de pares clave-valor a Properties.setProperties(properties). Cada par clave-valor del objeto en el parámetro se almacena como una propiedad separada:

service/propertyService.gs
try {
  // Set multiple script properties in one call.
  const scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.setProperties({
    'cow': 'moo',
    'sheep': 'baa',
    'chicken': 'cluck'
  });
} catch (err) {
  // TODO (developer) - Handle exception
  Logger.log('Failed with error %s', err.message);
}

Leer datos

Para recuperar un valor único que guardaste antes, llama a Properties.getProperty(key):

service/propertyService.gs
try {
  // Get the value for the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  const units = userProperties.getProperty('DISPLAY_UNITS');
  Logger.log('values of units %s', units);
} catch (err) {
  // TODO (developer) - Handle exception
  Logger.log('Failed with error %s', err.message);
}

Para recuperar todos los valores en el almacén de propiedades actual, llama a Properties.getProperties():

service/propertyService.gs
try {
  // Get multiple script properties in one call, then log them all.
  const scriptProperties = PropertiesService.getScriptProperties();
  const data = scriptProperties.getProperties();
  for (const key in data) {
    Logger.log('Key: %s, Value: %s', key, data[key]);
  }
} catch (err) {
  // TODO (developer) - Handle exception
  Logger.log('Failed with error %s', err.message);
}

Modificar datos

Los métodos getProperty() y getProperties() muestran una copia de los datos almacenados, no una vista en vivo, por lo que cambiar el objeto mostrado no actualizará el valor en el almacén de propiedades. Para actualizar los datos en la tienda, simplemente vuelve a guardarlos:

service/propertyService.gs
try {
  // Change the unit type in the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  let units = userProperties.getProperty('DISPLAY_UNITS');
  units = 'imperial'; // Only changes local value, not stored value.
  userProperties.setProperty('DISPLAY_UNITS', units); // Updates stored value.
} catch (err) {
  // TODO (developer) - Handle exception
  Logger.log('Failed with error %s', err.message);
}

Cómo borrar datos

Para borrar un solo valor, llama a Properties.deleteProperty(key):

service/propertyService.gs
try {
  // Delete the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('DISPLAY_UNITS');
} catch (err) {
  // TODO (developer) - Handle exception
  Logger.log('Failed with error %s', err.message);
}

Para borrar todas las propiedades en el almacén actual, llama a Properties.deleteAllProperties():

service/propertyService.gs
try {
  // Get user properties in the current script.
  const userProperties = PropertiesService.getUserProperties();
  // Delete all user properties in the current script.
  userProperties.deleteAllProperties();
} catch (err) {
  // TODO (developer) - Handle exception
  Logger.log('Failed with error %s', err.message);
}

Administrar las propiedades de las secuencias de comandos manualmente

Puedes agregar manualmente hasta cincuenta propiedades personalizadas, como strings en pares clave-valor, desde la página de configuración del proyecto. Para agregar más de cincuenta propiedades, debes hacerlo de manera programática con los métodos descritos anteriormente en Cómo guardar datos. Cuando configuras las propiedades de la secuencia de comandos desde la página de configuración del proyecto, no puedes hacer referencia a las variables de la secuencia de comandos.

Cómo agregar propiedades a la secuencia de comandos

  1. Abre tu proyecto de Apps Script.
  2. A la izquierda, haz clic en Configuración del proyecto Ícono de configuración del proyecto.
  3. Para agregar la primera propiedad, en Propiedades de secuencia de comandos, haz clic en Agregar propiedad de secuencia de comandos.
  4. Para agregar la segunda propiedad y las siguientes, en Propiedades de la secuencia de comandos, haz clic en Editar propiedades de la secuencia de comandos > Agregar propiedad de la secuencia de comandos.
  5. En Propiedad, ingresa el nombre de la clave.
  6. En Valor, ingresa el valor de la clave.
  7. (Opcional) Para agregar más propiedades, haga clic en Agregar propiedad de secuencia de comandos.
  8. Haz clic en Guardar propiedades de secuencia de comandos.

Editar propiedades de la secuencia de comandos

  1. Abre tu proyecto de Apps Script.
  2. A la izquierda, haz clic en Configuración del proyecto Ícono de configuración del proyecto.
  3. En Propiedades de la secuencia de comandos, haga clic en Editar propiedades de secuencia de comandos.
  4. Modifique el nombre y el valor de la clave de cada propiedad que desea modificar.
  5. Haz clic en Guardar propiedades de secuencia de comandos.

Borrar propiedades de la secuencia de comandos

  1. Abre tu proyecto de Apps Script.
  2. A la izquierda, haz clic en Configuración del proyecto Ícono de configuración del proyecto.
  3. En Propiedades de la secuencia de comandos, haga clic en Editar propiedades de secuencia de comandos.
  4. Junto a la propiedad que deseas borrar, haz clic en Quitar .
  5. Haz clic en Guardar propiedades de secuencia de comandos.