Page Summary

outlined_flag

• The Properties service stores simple key-value data for Apps Script projects, scoped to a script, user, or document.

• There are three types of property stores: Script properties (shared by all users), User properties (specific to the current user), and Document properties (specific to an add-on in a document).

• All data is stored as strings in key-value pairs, with non-string data types automatically converted.

• Data can be saved usingsetProperty for single values orsetProperties for multiple values.

• Data can be retrieved usinggetProperty for single values orgetProperties for all values in a store.

• Data can be modified by saving the updated value again usingsetProperty.

• Properties can be deleted individually withdeleteProperty or all at once withdeleteAllProperties.

• Script properties can be managed manually through the project settings page for up to fifty properties.

TheProperties service lets you storesimple data in key-value pairs scoped to one script, one user of a script, orone document in which anadd-on is used. It istypically used to store developer configuration or user preferences. Propertiesare never shared between scripts.

To view the daily quotas and storage limits for the Properties service, seeQuotas for Google Services.

Comparison of property stores

ThePropertiesServiceglobal object offers three methods, each of which returns a similarPropertiesobject but with different access rights, as shown in the following table:

Data format

The Properties service stores all data as strings in key-value pairs. Data typesthat are not already strings are automatically converted to strings, includingmethods contained within saved objects.

Saving data

To save a single value, call the methodProperties.setProperty(key,value)of the appropriate store, as shown in the following example:

try{// Set a property in each of the three property stores.constscriptProperties=PropertiesService.getScriptProperties();constuserProperties=PropertiesService.getUserProperties();constdocumentProperties=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 exceptionconsole.log("Failed with error %s",err.message);}

To save data in bulk, pass a map of key-value pairs toProperties.setProperties(properties).Each key-value pair of the object in the parameter is stored as a separateproperty:

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

Reading data

To retrieve a single value that you have previously saved, callProperties.getProperty(key):

try{// Get the value for the user property 'DISPLAY_UNITS'.constuserProperties=PropertiesService.getUserProperties();constunits=userProperties.getProperty("DISPLAY_UNITS");console.log("values of units %s",units);}catch(err){// TODO (developer) - Handle exceptionconsole.log("Failed with error %s",err.message);}

To retrieve all values in the current property store, callProperties.getProperties():

try{// Get multiple script properties in one call, then log them all.constscriptProperties=PropertiesService.getScriptProperties();constdata=scriptProperties.getProperties();for(constkeyindata){console.log("Key: %s, Value: %s",key,data[key]);}}catch(err){// TODO (developer) - Handle exceptionconsole.log("Failed with error %s",err.message);}

Modifying data

The methodsgetProperty() andgetProperties() return a copy of the storeddata, not a live view, so changing the returned object will not update the valuein the property store. To update the data in the store, simply save it again:

try{// Change the unit type in the user property 'DISPLAY_UNITS'.constuserProperties=PropertiesService.getUserProperties();letunits=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 exceptionconsole.log("Failed with error %s",err.message);}

Deleting data

To delete a single value, callProperties.deleteProperty(key):

try{// Delete the user property 'DISPLAY_UNITS'.constuserProperties=PropertiesService.getUserProperties();userProperties.deleteProperty("DISPLAY_UNITS");}catch(err){// TODO (developer) - Handle exceptionconsole.log("Failed with error %s",err.message);}

To delete all properties in the current store, callProperties.deleteAllProperties():

try{// Get user properties in the current script.constuserProperties=PropertiesService.getUserProperties();// Delete all user properties in the current script.userProperties.deleteAllProperties();}catch(err){// TODO (developer) - Handle exceptionconsole.log("Failed with error %s",err.message);}

Manage script properties manually

You can manually add up to fifty custom properties, as strings in key-valuepairs, from the project settings page. To add more than fifty properties, youneed to add them programmatically using the methods described above inSaving data.When you set script properties from the project settings page, you can’treference script variables.

Add script properties

1. Open your Apps Script project.
2. At the left, clickProject Settings.
3. To add the first property, underScript Properties clickAdd script property.
4. To add second and subsequent properties, underScript Properties clickEdit script properties>Add script property.
5. ForProperty, enter the key name.
6. ForValue, enter the value for the key.
7. (Optional) To add more properties, clickAdd script property.
8. ClickSave script properties.

Edit script properties

1. Open your Apps Script project.
2. At the left, clickProject Settings.
3. UnderScript Properties, clickEdit script properties.
4. Make changes to the key name and key value for each property you want to change.
5. ClickSave script properties.

Delete script properties

1. Open your Apps Script project.
2. At the left, clickProject Settings.
3. UnderScript Properties, clickEdit script properties.
4. Next to the property that you want to delete, click Removeclose.
5. ClickSave script properties.