Class Properties

Properties

The properties object acts as the interface to access user, document, or script properties. The specific property type depends on which of the three methods of PropertiesService the script called: PropertiesService.getDocumentProperties(), PropertiesService.getUserProperties(), or PropertiesService.getScriptProperties(). Properties cannot be shared between scripts. For more information about property types, see the guide to the Properties service.

Methods

MethodReturn typeBrief description
deleteAllProperties()PropertiesDeletes all properties in the current Properties store.
deleteProperty(key)PropertiesDeletes the property with the given key in the current Properties store.
getKeys()String[]Gets all keys in the current Properties store.
getProperties()ObjectGets a copy of all key-value pairs in the current Properties store.
getProperty(key)StringGets the value associated with the given key in the current Properties store, or null if no such key exists.
setProperties(properties)PropertiesSets all key-value pairs from the given object in the current Properties store.
setProperties(properties, deleteAllOthers)PropertiesSets all key-value pairs from the given object in the current Properties store, optionally deleting all other properties in the store.
setProperty(key, value)PropertiesSets the given key-value pair in the current Properties store.

Detailed documentation

deleteAllProperties()

Deletes all properties in the current Properties store.

// Deletes all user properties.
var userProperties = PropertiesService.getUserProperties();
userProperties.deleteAllProperties();

Return

Properties — this Properties store, for chaining


deleteProperty(key)

Deletes the property with the given key in the current Properties store.

// Deletes the user property 'nickname'.
var userProperties = PropertiesService.getUserProperties();
userProperties.deleteProperty('nickname');

Parameters

NameTypeDescription
keyStringthe key for the property to delete

Return

Properties — this Properties store, for chaining


getKeys()

Gets all keys in the current Properties store.

// Sets several properties, then logs the value of each key.
var scriptProperties = PropertiesService.getScriptProperties();
scriptProperties.setProperties({
  'cow': 'moo',
  'sheep': 'baa',
  'chicken': 'cluck'
});
var keys = scriptProperties.getKeys();
Logger.log('Animals known:');
for (var i = 0; i < keys.length; i++) {
  Logger.log(keys[i]);
}

Return

String[] — an array of all keys in the current Properties store


getProperties()

Gets a copy of all key-value pairs in the current Properties store. Note that the returned object is not a live view of the store. Consequently, changing the properties on the returned object will not automatically update them in storage, or vice versa.

// Sets several script properties, then retrieves them and logs them.
var scriptProperties = PropertiesService.getScriptProperties();
scriptProperties.setProperties({
  'cow': 'moo',
  'sheep': 'baa',
  'chicken': 'cluck'
});

var animalSounds = scriptProperties.getProperties();

// Logs:
// A chicken goes cluck!
// A cow goes moo!
// A sheep goes baa!
for (var kind in animalSounds) {
  Logger.log('A %s goes %s!', kind, animalSounds[kind]);
}

Return

Object — a copy of all key-value pairs in the current Properties store


getProperty(key)

Gets the value associated with the given key in the current Properties store, or null if no such key exists.

// Gets the user property 'nickname'.
var userProperties = PropertiesService.getUserProperties();
var nickname = userProperties.getProperty('nickname');
Logger.log(nickname);

Parameters

NameTypeDescription
keyStringthe key for the property value to retrieve

Return

String — the value associated with the given key in the current Properties store


setProperties(properties)

Sets all key-value pairs from the given object in the current Properties store.

// Sets multiple user properties at once.
var userProperties = PropertiesService.getUserProperties();
var newProperties = {nickname: 'Bob', region: 'US', language: 'EN'};
userProperties.setProperties(newProperties);

Parameters

NameTypeDescription
propertiesObjectan object containing key-values pairs to set

Return

Properties — this Properties store, for chaining


setProperties(properties, deleteAllOthers)

Sets all key-value pairs from the given object in the current Properties store, optionally deleting all other properties in the store.

// Sets multiple user properties at once while deleting all other user properties.
var userProperties = PropertiesService.getUserProperties();
var newProperties = {nickname: 'Bob', region: 'US', language: 'EN'};
userProperties.setProperties(newProperties, true);

Parameters

NameTypeDescription
propertiesObjectan object containing key-values pairs to set
deleteAllOthersBooleantrue to delete all other key-value pairs in the properties object; false to not

Return

Properties — this Properties store, for chaining


setProperty(key, value)

Sets the given key-value pair in the current Properties store.

// Sets the user property 'nickname' to 'Bobby'.
var userProperties = PropertiesService.getUserProperties();
userProperties.setProperty('nickname', 'Bobby');

Parameters

NameTypeDescription
keyStringthe key for the property
valueStringthe value to associate with the key

Return

Properties — this Properties store, for chaining