Class Protection

Access and modify protected ranges and sheets. A protected range can protect either a static range of cells or a named range. A protected sheet may include unprotected regions. For spreadsheets created with the older version of Google Sheets, use the PageProtection class instead.

// Protect range A1:B10, then remove all other users from the list of editors.
var ss = SpreadsheetApp.getActive();
var range = ss.getRange('A1:B10');
var protection = range.protect().setDescription('Sample protected range');

// Ensure the current user is an editor before removing others. Otherwise, if the user's edit
// permission comes from a group, the script throws an exception upon removing the group.
var me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

// Remove all range protections in the spreadsheet that the user has permission to edit.
var ss = SpreadsheetApp.getActive();
var protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (var i = 0; i < protections.length; i++) {
  var protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}

// Protect the active sheet, then remove all other users from the list of editors.
var sheet = SpreadsheetApp.getActiveSheet();
var protection = sheet.protect().setDescription('Sample protected sheet');

// Ensure the current user is an editor before removing others. Otherwise, if the user's edit
// permission comes from a group, the script throws an exception upon removing the group.
var me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

Methods

Method	Return type	Brief description
`addEditor(emailAddress)`	`Protection`	Adds the given user to the list of editors for the protected sheet or range.
`addEditor(user)`	`Protection`	Adds the given user to the list of editors for the protected sheet or range.
`addEditors(emailAddresses)`	`Protection`	Adds the given array of users to the list of editors for the protected sheet or range.
`addTargetAudience(audienceId)`	`Protection`	Adds the specified target audience as an editor of the protected range.
`canDomainEdit()`	`Boolean`	Determines whether all users in the domain that owns the spreadsheet have permission to edit the protected range or sheet.
`canEdit()`	`Boolean`	Determines whether the user has permission to edit the protected range or sheet.
`getDescription()`	`String`	Gets the description of the protected range or sheet.
`getEditors()`	`User[]`	Gets the list of editors for the protected range or sheet.
`getProtectionType()`	`ProtectionType`	Gets the type of the protected area, either `RANGE` or `SHEET`.
`getRange()`	`Range`	Gets the range that is being protected.
`getRangeName()`	`String`	Gets the name of the protected range if it is associated with a named range.
`getTargetAudiences()`	`TargetAudience[]`	Returns the IDs of the target audiences that can edit the protected range.
`getUnprotectedRanges()`	`Range[]`	Gets an array of unprotected ranges within a protected sheet.
`isWarningOnly()`	`Boolean`	Determines if the protected area is using "warning based" protection.
`remove()`	`void`	Unprotects the range or sheet.
`removeEditor(emailAddress)`	`Protection`	Removes the given user from the list of editors for the protected sheet or range.
`removeEditor(user)`	`Protection`	Removes the given user from the list of editors for the protected sheet or range.
`removeEditors(emailAddresses)`	`Protection`	Removes the given array of users from the list of editors for the protected sheet or range.
`removeTargetAudience(audienceId)`	`Protection`	Removes the specified target audience as an editor of the protected range.
`setDescription(description)`	`Protection`	Sets the description of the protected range or sheet.
`setDomainEdit(editable)`	`Protection`	Sets whether all users in the domain that owns the spreadsheet have permission to edit the protected range or sheet.
`setNamedRange(namedRange)`	`Protection`	Associates the protected range with an existing named range.
`setRange(range)`	`Protection`	Adjusts the range that is being protected.
`setRangeName(rangeName)`	`Protection`	Associates the protected range with an existing named range.
`setUnprotectedRanges(ranges)`	`Protection`	Unprotects the given array of ranges within a protected sheet.
`setWarningOnly(warningOnly)`	`Protection`	Sets whether or not this protected range is using "warning based" protection.

Detailed documentation

`addEditor(emailAddress)`

Adds the given user to the list of editors for the protected sheet or range. This method does not automatically give the user permission to edit the spreadsheet itself; to do that in addition, call Spreadsheet.addEditor(emailAddress).

Parameters

Name	Type	Description
`emailAddress`	`String`	The email address of the user to add.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`addEditor(user)`

Parameters

Name	Type	Description
`user`	`User`	A representation of the user to add.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`addEditors(emailAddresses)`

Adds the given array of users to the list of editors for the protected sheet or range. This method does not automatically give the users permission to edit the spreadsheet itself; to do that in addition, call Spreadsheet.addEditors(emailAddresses).

Parameters

Name	Type	Description
`emailAddresses`	`String[]`	An array of email addresses of the users to add.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`addTargetAudience(audienceId)`

Adds the specified target audience as an editor of the protected range.

Parameters

Name	Type	Description
`audienceId`	`String`	The ID of the target audience to add.

Return

Protection — The object representing the protection settings, for chaining.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`canDomainEdit()`

Determines whether all users in the domain that owns the spreadsheet have permission to edit the protected range or sheet. Throws an exception if the user does not have permission to edit the protected range or sheet.

Return

Boolean — true if all users in the domain that owns the spreadsheet have permission to edit the protected range or sheet; false if not

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`canEdit()`

Determines whether the user has permission to edit the protected range or sheet. The spreadsheet owner is always able to edit protected ranges and sheets.

// Remove all range protections in the spreadsheet that the user has permission to edit.
var ss = SpreadsheetApp.getActive();
var protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (var i = 0; i < protections.length; i++) {
  var protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}

Return

Boolean — true if the user has permission to edit the protected range or sheet; false if not

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getDescription()`

Gets the description of the protected range or sheet. If no description is set, this method returns an empty string.

Return

String — the description of the protected range or sheet, or an empty string if no description is set

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getEditors()`

Gets the list of editors for the protected range or sheet. Throws an exception if the user does not have permission to edit the protected range or sheet.

// Protect the active sheet, then remove all other users from the list of editors.
var sheet = SpreadsheetApp.getActiveSheet();
var protection = sheet.protect().setDescription('Sample protected sheet');

// Ensure the current user is an editor before removing others. Otherwise, if the user's edit
// permission comes from a group, the script throws an exception upon removing the group.
var me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

Return

User[] — an array of users with permission to edit the protected range or sheet

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getProtectionType()`

Gets the type of the protected area, either RANGE or SHEET.

Return

ProtectionType — the type of protected area, either RANGE or SHEET

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getRange()`

Gets the range that is being protected. If the protection applies to the sheet instead of a range, this method returns a range that spans the entire sheet.

Return

Range — the range that is being protected

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getRangeName()`

Gets the name of the protected range if it is associated with a named range. Returns null if the protection is not associated with a named range. Note that scripts must explicitly call setRangeName(rangeName) to associate a protected range with a named range; calling Range.protect() to create a protection from a Range that happens to be a named range, without calling setRangeName(rangeName), is not sufficient to associate them. However, creating a protected range from a named range in the Google Sheets UI associates them automatically.

// Protect a named range in a spreadsheet and log the name of the protected range.
var ss = SpreadsheetApp.getActive();
var range = ss.getRange('A1:B10');
var protection = range.protect();
ss.setNamedRange('Test', range);       // Create a named range.
protection.setRangeName('Test');       // Associate the protection with the named range.
Logger.log(protection.getRangeName()); // Verify the name of the protected range.

Return

String — the name of the protected named range, or null if the protected range is not associated with a named range

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getTargetAudiences()`

Returns the IDs of the target audiences that can edit the protected range.

Return

TargetAudience[] — An array of the IDs of target audiences.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getUnprotectedRanges()`

Gets an array of unprotected ranges within a protected sheet. If the Protection object corresponds to a protected range instead of a protected sheet, this method returns an empty array. To change the unprotected ranges, use setUnprotectedRanges(ranges) to set a new array of ranges; to re-protect the entire sheet, set an empty array.

// Unprotect cells E2:F5 in addition to any other unprotected ranges in the protected sheet.
var sheet = SpreadsheetApp.getActiveSheet();
var protection = sheet.protect();
var unprotected = protection.getUnprotectedRanges();
unprotected.push(sheet.getRange('E2:F5'));
protection.setUnprotectedRanges(unprotected);

Return

Range[] — an array of unprotected ranges within a protected sheet

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`isWarningOnly()`

Determines if the protected area is using "warning based" protection. Warning-based protection means that every user can edit data in the area, except editing prompts a warning asking the user to confirm the edit. By default, protected ranges or sheets are not warning-based. To change to the warning state, use setWarningOnly(warningOnly).

Return

Boolean — true if the protected range or sheet is only using warning-based protection

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`remove()`

Unprotects the range or sheet.

// Remove all range protections in the spreadsheet that the user has permission to edit.
var ss = SpreadsheetApp.getActive();
var protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (var i = 0; i < protections.length; i++) {
  var protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}

// Remove sheet protection from the active sheet, if the user has permission to edit it.
var sheet = SpreadsheetApp.getActiveSheet();
var protection = sheet.getProtections(SpreadsheetApp.ProtectionType.SHEET)[0];
if (protection && protection.canEdit()) {
  protection.remove();
}

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`removeEditor(emailAddress)`

Removes the given user from the list of editors for the protected sheet or range. Note that if the user is a member of a Google Group that has edit permission, or if all users in the domain have edit permission, the user are still be able to edit the protected area. Neither the owner of the spreadsheet nor the current user can be removed.

Parameters

Name	Type	Description
`emailAddress`	`String`	The email address of the user to remove.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`removeEditor(user)`

Removes the given user from the list of editors for the protected sheet or range. Note that if the user is a member of a Google Group that has edit permission, or if all users in the domain have edit permission, the user is still be able to edit the protected area as well. Neither the owner of the spreadsheet nor the current user can be removed.

Parameters

Name	Type	Description
`user`	`User`	A representation of the user to remove.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`removeEditors(emailAddresses)`

Removes the given array of users from the list of editors for the protected sheet or range. Note that if any of the users are members of a Google Group that has edit permission, or if all users in the domain have edit permission, those users are still be able to edit the protected area. Neither the owner of the spreadsheet nor the current user can be removed.

// Protect the active sheet, then remove all other users from the list of editors.
var sheet = SpreadsheetApp.getActiveSheet();
var protection = sheet.protect().setDescription('Sample protected sheet');

// Ensure the current user is an editor before removing others. Otherwise, if the user's edit
// permission comes from a group, the script throws an exception upon removing the group.
var me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

Parameters

Name	Type	Description
`emailAddresses`	`String[]`	An array of email addresses of the users to remove.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`removeTargetAudience(audienceId)`

Removes the specified target audience as an editor of the protected range.

Parameters

Name	Type	Description
`audienceId`	`String`	The ID of the target audience to remove.

Return

Protection — The object representing the protection settings, for chaining.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`setDescription(description)`

Sets the description of the protected range or sheet.

Parameters

Name	Type	Description
`description`	`String`	The description of the protected range or sheet.

Return

Protection — The object representing the protection settings, for chaining.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`setDomainEdit(editable)`

Sets whether all users in the domain that owns the spreadsheet have permission to edit the protected range or sheet. Note that any users who have explicit edit permission are able to edit the protected area regardless of this setting. Throws an exception if the spreadsheet does not belong to a Google Workspace domain (that is, if it is owned by a gmail.com account).

Parameters

Name	Type	Description
`editable`	`Boolean`	`true` if all users in the domain that owns the spreadsheet should have permission to edit the protected range or sheet; `false` if not.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`setNamedRange(namedRange)`

Associates the protected range with an existing named range. If the named range covers a different area from the current protected range, this method moves the protection to cover the the named range instead. The named range must be on the same sheet as the current protected range. Note that scripts must explicitly call this method to associate a protected range with a named range; calling Range.protect() to create a protection from a Range that happens to be a named range, without calling setRangeName(rangeName), is not sufficient to associate them. However, creating a protected range from a named range in the Google Sheets UI associates them automatically.

Parameters

Name	Type	Description
`namedRange`	`NamedRange`	The existing named range to associate with the protected range.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`setRange(range)`

Adjusts the range that is being protected. If the given range covers a different area from the current protected range, this method moves the protection to cover the new range instead.

Parameters

Name	Type	Description
`range`	`Range`	The new range to protect from edits.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`setRangeName(rangeName)`

// Protect a named range in a spreadsheet and log the name of the protected range.
var ss = SpreadsheetApp.getActive();
var range = ss.getRange('A1:B10');
var protection = range.protect();
ss.setNamedRange('Test', range);       // Create a named range.
protection.setRangeName('Test');       // Associate the protection with the named range.
Logger.log(protection.getRangeName()); // Verify the name of the protected range.

Parameters

Name	Type	Description
`rangeName`	`String`	The name of the named range to be protected.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`setUnprotectedRanges(ranges)`

Unprotects the given array of ranges within a protected sheet. Throws an exception if the Protection object corresponds to a protected range instead of a protected sheet or if any of the ranges are not on the protected sheet. To change the unprotected ranges, set a new array of ranges; to re-protect the entire sheet, set an empty array.

// Protect the active sheet except B2:C5, then remove all other users from the list of editors.
var sheet = SpreadsheetApp.getActiveSheet();
var protection = sheet.protect().setDescription('Sample protected sheet');
var unprotected = sheet.getRange('B2:C5');
protection.setUnprotectedRanges([unprotected]);

// Ensure the current user is an editor before removing others. Otherwise, if the user's edit
// permission comes from a group, the script throws an exception upon removing the group.
var me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

Parameters

Name	Type	Description
`ranges`	`Range[]`	The array of ranges to leave unprotected within a protected sheet.

Return

Protection — the object representing the protection settings, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`setWarningOnly(warningOnly)`

Sets whether or not this protected range is using "warning based" protection. Warning-based protection means that every user can edit data in the area, except editing prompts a warning asking the user to confirm the edit. By default, protected ranges or sheets are not warning-based. To check warning state, use isWarningOnly().

Parameters

Name	Type	Description
`warningOnly`	`Boolean`

Return

Protection — the object representing the protection settings, for chaining.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets