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
Method | Return type | Brief description |
---|---|---|
deleteAllProperties() | Properties | Deletes all properties in the current Properties store. |
deleteProperty(key) | Properties | Deletes the property with the given key in the current Properties store. |
getKeys() | String[] | Gets all keys in the current Properties store. |
getProperties() | Object | Gets a copy of all key-value pairs in the current Properties store. |
getProperty(key) | String | Gets the value associated with the given key in the current Properties store, or null if no such key exists. |
setProperties(properties) | Properties | Sets all key-value pairs from the given object in the current Properties store. |
setProperties(properties, deleteAllOthers) | Properties | Sets all key-value pairs from the given object in the current Properties store,
optionally deleting all other properties in the store. |
setProperty(key, value) | Properties | Sets 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
Name | Type | Description |
---|---|---|
key | String | the 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
Name | Type | Description |
---|---|---|
key | String | the 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
Name | Type | Description |
---|---|---|
properties | Object | an 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
Name | Type | Description |
---|---|---|
properties | Object | an object containing key-values pairs to set |
deleteAllOthers | Boolean | true 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
Name | Type | Description |
---|---|---|
key | String | the key for the property |
value | String | the value to associate with the key |
Return
Properties
— this Properties
store, for chaining