Class Protection

  • Protected ranges can cover static or named ranges, and protected sheets can have unprotected areas.

  • You can manage editors for protected ranges and sheets, adding or removing them by email address or User object.

  • Protection can be removed entirely from ranges or sheets if the user has edit permission.

  • Descriptions and warning-only settings can be applied and checked for protected areas.

  • You can retrieve information about protected areas, such as the range, type (RANGE or SHEET), and editors.

Protection

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

// Protect range A1:B10, then remove all other users from the list of editors.constss=SpreadsheetApp.getActive();constrange=ss.getRange('A1:B10');constprotection=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.constme=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.constss=SpreadsheetApp.getActive();constprotections=ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);for(leti=0;i <protections.length;i++){constprotection=protections[i];if(protection.canEdit()){protection.remove();}}
// Protect the active sheet, then remove all other users from the list of// editors.constsheet=SpreadsheetApp.getActiveSheet();constprotection=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.constme=Session.getEffectiveUser();protection.addEditor(me);protection.removeEditors(protection.getEditors());if(protection.canDomainEdit()){protection.setDomainEdit(false);}

Methods

MethodReturn typeBrief description
addEditor(emailAddress)ProtectionAdds the given user to the list of editors for the protected sheet or range.
addEditor(user)ProtectionAdds the given user to the list of editors for the protected sheet or range.
addEditors(emailAddresses)ProtectionAdds the given array of users to the list of editors for the protected sheet or range.
addTargetAudience(audienceId)ProtectionAdds the specified target audience as an editor of the protected range.
canDomainEdit()BooleanDetermines whether all users in the domain that owns the spreadsheet have permission to editthe protected range or sheet.
canEdit()BooleanDetermines whether the user has permission to edit the protected range or sheet.
getDescription()StringGets the description of the protected range or sheet.
getEditors()User[]Gets the list of editors for the protected range or sheet.
getProtectionType()ProtectionTypeGets the type of the protected area, eitherRANGE orSHEET.
getRange()RangeGets the range that is being protected.
getRangeName()String|nullGets 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()BooleanDetermines if the protected area is using "warning based" protection.
remove()voidUnprotects the range or sheet.
removeEditor(emailAddress)ProtectionRemoves the given user from the list of editors for the protected sheet or range.
removeEditor(user)ProtectionRemoves the given user from the list of editors for the protected sheet or range.
removeEditors(emailAddresses)ProtectionRemoves the given array of users from the list of editors for the protected sheet or range.
removeTargetAudience(audienceId)ProtectionRemoves the specified target audience as an editor of the protected range.
setDescription(description)ProtectionSets the description of the protected range or sheet.
setDomainEdit(editable)ProtectionSets whether all users in the domain that owns the spreadsheet have permission to edit theprotected range or sheet.
setNamedRange(namedRange)ProtectionAssociates the protected range with an existing named range.
setRange(range)ProtectionAdjusts the range that is being protected.
setRangeName(rangeName)ProtectionAssociates the protected range with an existing named range.
setUnprotectedRanges(ranges)ProtectionUnprotects the given array of ranges within a protected sheet.
setWarningOnly(warningOnly)ProtectionSets 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 doesnot automatically give the user permission to edit the spreadsheet itself; to do that inaddition, callSpreadsheet.addEditor(emailAddress).

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Adds an editor to the spreadsheet using an email address.// TODO(developer): Replace the email address with a valid email.ss.addEditor('cloudysanfrancisco@gmail.com');// Gets a sheet by its name and protects it.constsheet=ss.getSheetByName('Sheet1');constsampleProtectedSheet=sheet.protect();// Adds an editor of the protected sheet using an email address.// TODO(developer): Replace the email address with a valid email.sampleProtectedSheet.addEditor('cloudysanfrancisco@gmail.com');// Gets the editors of the protected sheet.consteditors=sampleProtectedSheet.getEditors();// Logs the editors' email addresses to the console.for(consteditorofeditors){console.log(editor.getEmail());}

Parameters

NameTypeDescription
emailAddressStringThe 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 followingscopes:

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

addEditor(user)

Adds the given user to the list of editors for the protected sheet or range. This method doesnot automatically give the user permission to edit the spreadsheet itself; to do that inaddition, callSpreadsheet.addEditor(user).

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets a sheet by its name.constsheet=ss.getSheetByName('Sheet1');// Protects the sheet.constsampleProtectedSheet=sheet.protect();// Adds the active user as an editor of the protected sheet.sampleProtectedSheet.addEditor(Session.getActiveUser());// Gets the editors of the protected sheet.consteditors=sampleProtectedSheet.getEditors();// Logs the editors' email addresses to the console.for(consteditorofeditors){console.log(editor.getEmail());}

Parameters

NameTypeDescription
userUserA 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 followingscopes:

  • 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. Thismethod does not automatically give the users permission to edit the spreadsheet itself; to dothat in addition, callSpreadsheet.addEditors(emailAddresses).

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets a sheet by its name.constsheet=ss.getSheetByName('Sheet1');// Creates variables for the email addresses to add as editors.// TODO(developer): Replace the email addresses with valid ones.constTEST_EMAIL_1='cloudysanfrancisco@gmail.com';constTEST_EMAIL_2='baklavainthebalkans@gmail.com';// Protects the sheet.constsampleProtectedSheet=sheet.protect();// Adds editors to the protected sheet using the email address variables.sampleProtectedSheet.addEditors([TEST_EMAIL_1,TEST_EMAIL_2]);// Gets the editors of the protected sheet.consteditors=sampleProtectedSheet.getEditors();// Logs the editors' email addresses to the console.for(consteditorofeditors){console.log(editor.getEmail());}

Parameters

NameTypeDescription
emailAddressesString[]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 followingscopes:

  • 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

NameTypeDescription
audienceIdStringThe 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 followingscopes:

  • 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 editthe protected range or sheet. Throws an exception if the user does not have permission to editthe protected range or sheet.

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets a sheet by its name.constsheet=ss.getSheetByName('Sheet1');// Protects the sheet.constsampleProtectedSheet=sheet.protect();// Logs whether domain users have permission to edit the protected sheet to the// console.console.log(sampleProtectedSheet.canDomainEdit());

Return

Booleantrue if all users in the domain that owns the spreadsheet have permission to edit the protected range or sheet;false if they don't.

Authorization

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

  • 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. Thespreadsheet owner is always able to edit protected ranges and sheets.

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

Return

Booleantrue 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 followingscopes:

  • 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 methodreturns an empty string.

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets a sheet by its name.constsheet=ss.getSheetByName('Sheet1');// Protects the sheet and sets the description.constsampleProtectedSheet=sheet.protect().setDescription('Sample sheet is protected');// Gets the description of the protected sheet and logs it to the console.constsampleProtectedSheetDescription=sampleProtectedSheet.getDescription();console.log(sampleProtectedSheetDescription);

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 followingscopes:

  • 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 doesnot have permission to edit the protected range or sheet.

// Protect the active sheet, then remove all other users from the list of// editors.constsheet=SpreadsheetApp.getActiveSheet();constprotection=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.constme=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 followingscopes:

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

getProtectionType()

Gets the type of the protected area, eitherRANGE orSHEET.

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets a sheet by its name.constsheet=ss.getSheetByName('Sheet1');// Protects the sheet.constsampleProtectedSheet=sheet.protect();// Gets the type of the protected area.constprotectionType=sampleProtectedSheet.getProtectionType();// Logs 'SHEET'to the console since the type of the protected area is a sheet.console.log(protectionType.toString());

Return

ProtectionType — The type of protected area, eitherRANGE orSHEET.

Authorization

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

  • 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 arange, this method returns a range that spans the entire sheet.

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets a sheet by its name.constsheet=ss.getSheetByName('Sheet1');// Gets the range 'A1:B10' of Sheet1.constrange=sheet.getRange('A1:B10');// Makes cells A1:B10 a protected range.constsampleProtectedRange=range.protect();// Gets the protected ranges on the sheet.constprotections=sheet.getProtections(SpreadsheetApp.ProtectionType.RANGE);// Logs the A1 notation of the first protected range on the sheet.console.log(protections[0].getRange().getA1Notation());

Return

Range — The range that is being protected.

Authorization

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

  • 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. Returnsnull if the protection is not associated with a named range. Note that scripts must explicitlycallsetRangeName(rangeName) to associate a protected range with a named range; callingRange.protect() to create a protection from aRange that happens to be anamed range, without callingsetRangeName(rangeName), is not sufficient to associatethem. However, creating a protected range from a named range in the Google Sheets UI associatesthem automatically.

// Protect a named range in a spreadsheet and log the name of the protected// range.constss=SpreadsheetApp.getActive();constrange=ss.getRange('A1:B10');constprotection=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|null — the name of the protected named range, ornull 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 followingscopes:

  • 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 followingscopes:

  • 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 theProtection objectcorresponds to a protected range instead of a protected sheet, this method returns an emptyarray. To change the unprotected ranges, usesetUnprotectedRanges(ranges) to set anew 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.constsheet=SpreadsheetApp.getActiveSheet();constprotection=sheet.protect();constunprotected=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 followingscopes:

  • 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 protectionmeans that every user can edit data in the area, except editing prompts a warning asking theuser to confirm the edit. By default, protected ranges or sheets are not warning-based. Tochange to the warning state, usesetWarningOnly(warningOnly).

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets a sheet by its name.constsheet=ss.getSheetByName('Sheet1');// Protects the sheet.constsampleProtectedSheet=sheet.protect();// Sets the warning status for the protected sheet as true.sampleProtectedSheet.setWarningOnly(true);constprotectedSheetWarningStatus=sampleProtectedSheet.isWarningOnly();// Logs the warning status of the protected sheet to the console.console.log(protectedSheetWarningStatus);

Return

Booleantrue 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 followingscopes:

  • 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.constss=SpreadsheetApp.getActive();constprotections=ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);for(leti=0;i <protections.length;i++){constprotection=protections[i];if(protection.canEdit()){protection.remove();}}
// Remove sheet protection from the active sheet, if the user has permission to// edit it.constsheet=SpreadsheetApp.getActiveSheet();constprotection=sheet.getProtections(SpreadsheetApp.ProtectionType.SHEET)[0];if(protection?.canEdit()){protection.remove();}

Authorization

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

  • 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 ifthe user is a member of a Google Group that has edit permission, or if all users in the domainhave edit permission, the user are still be able to edit the protected area. Neither the ownerof the spreadsheet nor the current user can be removed.

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets a sheet by its name.constsheet=ss.getSheetByName('Sheet1');// Creates a variable for an email address.// TODO(developer): Replace the email address with a valid one.constTEST_EMAIL='baklavainthebalkans@gmail.com';// Protects the sheet.constsampleProtectedSheet=sheet.protect();// Adds an editor to the protected sheet using the email address variable.sampleProtectedSheet.addEditor(TEST_EMAIL);// Removes the editor from the protected sheet using the email address variable.sampleProtectedSheet.removeEditor(TEST_EMAIL);// Gets the editors of the protected sheet.consteditors=sampleProtectedSheet.getEditors();// Logs the editors' email addresses to the console.for(consteditorofeditors){console.log(editor.getEmail());}

Parameters

NameTypeDescription
emailAddressStringThe 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 followingscopes:

  • 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 ifthe user is a member of a Google Group that has edit permission, or if all users in the domainhave edit permission, the user is still be able to edit the protected area as well. Neither theowner of the spreadsheet nor the current user can be removed.

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets a sheet by its name.constsheet=ss.getSheetByName('Sheet1');// Protects the sheet.constsampleProtectedSheet=sheet.protect();// Removes the active user from the editors of the protected sheet.sampleProtectedSheet.removeEditor(Session.getActiveUser());// Gets the editors of the protected sheet.consteditors=sampleProtectedSheet.getEditors();// Logs the editors' email addresses to the console.for(consteditorofeditors){console.log(editor.getEmail());}

Parameters

NameTypeDescription
userUserA 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 followingscopes:

  • 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 allusers in the domain have edit permission, those users are still be able to edit the protectedarea. 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.constsheet=SpreadsheetApp.getActiveSheet();constprotection=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.constme=Session.getEffectiveUser();protection.addEditor(me);protection.removeEditors(protection.getEditors());if(protection.canDomainEdit()){protection.setDomainEdit(false);}

Parameters

NameTypeDescription
emailAddressesString[]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 followingscopes:

  • 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

NameTypeDescription
audienceIdStringThe 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 followingscopes:

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

setDescription(description)

Sets the description of the protected range or sheet.

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets the sheet 'Sheet1' by its name.constsheet=ss.getSheetByName('Sheet1');// Protects the sheet.constsampleProtectedSheet=sheet.protect();// Sets the sheet description to 'Sheet1 is protected.'sampleProtectedSheet.setDescription('Sheet1 is protected');// Gets the description of the protected sheet.constsampleProtectedSheetDescription=sampleProtectedSheet.getDescription();// Logs the description of the protected sheet to the console.console.log(sampleProtectedSheetDescription);

Parameters

NameTypeDescription
descriptionStringThe 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 followingscopes:

  • 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 theprotected range or sheet. Note that any users who have explicit edit permission are able toedit the protected area regardless of this setting. Throws an exception if the spreadsheet doesnot belong to a Google Workspace domain (that is, if it is owned by a gmail.com account).

Parameters

NameTypeDescription
editableBooleantrue 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 followingscopes:

  • 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 adifferent area from the current protected range, this method moves the protection to cover thethe named range instead. The named range must be on the same sheet as the current protectedrange. Note that scripts must explicitly call this method to associate a protected range with anamed range; callingRange.protect() to create a protection from aRangethat happens to be a named range, without callingsetRangeName(rangeName), is notsufficient to associate them. However, creating a protected range from a named range in theGoogle Sheets UI associates them automatically.

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Protects cells A1:D10 on Sheet1.constsheet=ss.getSheetByName('Sheet1');constprotectedRange=sheet.getRange('A1:D10').protect();// Logs the current protected range, A1:D10.console.log(protectedRange.getRange().getA1Notation());// Creates a named range for cells E1:J10 called 'NewRange.'constnewRange=sheet.getRange('E1:J10');ss.setNamedRange('NewRange',newRange);constnamedRange=ss.getNamedRanges()[0];// Updates the protected range to the named range, 'NewRange.'// This updates the protected range on Sheet1 from A1:D10 to E1:J10.protectedRange.setNamedRange(namedRange);// Logs the updated protected range to the console.console.log(protectedRange.getRange().getA1Notation());

Parameters

NameTypeDescription
namedRangeNamedRangeThe 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 followingscopes:

  • 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 thecurrent protected range, this method moves the protection to cover the new range instead.

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Protects cells A1:D10 on Sheet1 of the spreadsheet.constsheet=ss.getSheetByName('Sheet1');constprotectedRange=sheet.getRange('A1:D10').protect();// Logs the original protected range, A1:D10, to the console.console.log(protectedRange.getRange().getA1Notation());// Gets the range E1:J10.constnewRange=sheet.getRange('E1:J10');// Updates the protected range to E1:J10.protectedRange.setRange(newRange);// Logs the updated protected range to the console.console.log(protectedRange.getRange().getA1Notation());

Parameters

NameTypeDescription
rangeRangeThe 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 followingscopes:

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

setRangeName(rangeName)

Associates the protected range with an existing named range. If the named range covers adifferent area from the current protected range, this method moves the protection to cover thethe named range instead. The named range must be on the same sheet as the current protectedrange. Note that scripts must explicitly call this method to associate a protected range with anamed range; callingRange.protect() to create a protection from aRangethat happens to be a named range, without callingsetRangeName(rangeName), is notsufficient to associate them. However, creating a protected range from a named range in theGoogle Sheets UI associates them automatically.

// Protect a named range in a spreadsheet and log the name of the protected// range.constss=SpreadsheetApp.getActive();constrange=ss.getRange('A1:B10');constprotection=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

NameTypeDescription
rangeNameStringThe 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 followingscopes:

  • 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 theProtection object corresponds to a protected range instead of a protected sheet or ifany of the ranges are not on the protected sheet. To change the unprotected ranges, set a newarray 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.constsheet=SpreadsheetApp.getActiveSheet();constprotection=sheet.protect().setDescription('Sample protected sheet');constunprotected=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.constme=Session.getEffectiveUser();protection.addEditor(me);protection.removeEditors(protection.getEditors());if(protection.canDomainEdit()){protection.setDomainEdit(false);}

Parameters

NameTypeDescription
rangesRange[]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 followingscopes:

  • 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-basedprotection means that every user can edit data in the area, except editing prompts a warningasking the user to confirm the edit. By default, protected ranges or sheets are notwarning-based. To check warning state, useisWarningOnly().

// Opens the spreadsheet file by its URL. If you created your script from within// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()// instead.// TODO(developer): Replace the URL with your own.constss=SpreadsheetApp.openByUrl('https://docs.google.com/spreadsheets/d/abc123456/edit',);// Gets the sheet 'Sheet1' by its name.constsheet=ss.getSheetByName('Sheet1');// Protects the sheet and sets the protection to warning-based.constsampleProtectedSheet=sheet.protect().setWarningOnly(true);// Logs whether the protected sheet is warning-based to the console.console.log(sampleProtectedSheet.isWarningOnly());

Parameters

NameTypeDescription
warningOnlyBoolean

Return

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

Authorization

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

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-11 UTC.