Class Protection

Proteção

Acessar e modificar intervalos e páginas protegidas. Um intervalo protegido pode proteger um intervalo estático de células ou um nomeado. Uma página protegida pode incluir regiões não protegidas. Para planilhas criadas com a versão mais antiga das Planilhas Google, use a classe PageProtection. 

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

Métodos

MétodoTipo de retornoBreve descrição
addEditor(emailAddress)ProtectionAdiciona o usuário à lista de editores da planilha ou do intervalo protegido.
addEditor(user)ProtectionAdiciona o usuário à lista de editores da planilha ou do intervalo protegido.
addEditors(emailAddresses)ProtectionAdiciona a matriz de usuários à lista de editores da planilha ou do intervalo protegido.
addTargetAudience(audienceId)ProtectionAdiciona o público-alvo especificado como editor do intervalo protegido.
canDomainEdit()BooleanDetermina se todos os usuários no domínio que é proprietário da planilha têm permissão para editar a planilha ou o intervalo protegido.
canEdit()BooleanDetermina se o usuário tem permissão para editar a planilha ou o intervalo protegido.
getDescription()StringRetorna a descrição do intervalo ou da página protegida.
getEditors()User[]Recebe a lista de editores do intervalo ou da página protegida.
getProtectionType()ProtectionTypeRecebe o tipo da área protegida, RANGE ou SHEET.
getRange()RangeRecebe o intervalo que está sendo protegido.
getRangeName()StringRetorna o nome do intervalo protegido se ele estiver associado a um intervalo nomeado.
getTargetAudiences()TargetAudience[]Retorna os IDs dos públicos-alvo que podem editar o intervalo protegido.
getUnprotectedRanges()Range[]Recebe uma matriz de intervalos não protegidos em uma página protegida.
isWarningOnly()BooleanDetermina se a área protegida está usando a proteção "com base em avisos".
remove()voidRemove a proteção do intervalo ou da página.
removeEditor(emailAddress)ProtectionRemove o usuário da lista de editores da planilha ou do intervalo protegido.
removeEditor(user)ProtectionRemove o usuário da lista de editores da planilha ou do intervalo protegido.
removeEditors(emailAddresses)ProtectionRemove a matriz de usuários da lista de editores da planilha ou do intervalo protegido.
removeTargetAudience(audienceId)ProtectionRemove o público-alvo especificado como editor do intervalo protegido.
setDescription(description)ProtectionDefine a descrição do intervalo ou da página protegida.
setDomainEdit(editable)ProtectionDefine se todos os usuários no domínio que são proprietários da planilha têm permissão para editar a folha ou o intervalo protegido.
setNamedRange(namedRange)ProtectionAssocia o intervalo protegido a um intervalo nomeado.
setRange(range)ProtectionAjusta o intervalo que está sendo protegido.
setRangeName(rangeName)ProtectionAssocia o intervalo protegido a um intervalo nomeado.
setUnprotectedRanges(ranges)ProtectionRemove a proteção de uma matriz de intervalos em uma página protegida.
setWarningOnly(warningOnly)ProtectionDefine se o intervalo protegido está usando ou não a proteção "com base em avisos".

Documentação detalhada

addEditor(emailAddress)

Adiciona o usuário à lista de editores da planilha ou do intervalo protegido. Esse método não dá automaticamente ao usuário permissão para editar a planilha. Para fazer isso, chame Spreadsheet.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.
const ss = 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.
const sheet = ss.getSheetByName('Sheet1');
const sampleProtectedSheet = 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.
const editors = sampleProtectedSheet.getEditors();

// Logs the editors' email addresses to the console.
for (const editor of editors) {
  console.log(editor.getEmail());
}

Parâmetros

NomeTipoDescrição
emailAddressStringO endereço de e-mail do usuário a ser adicionado.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

addEditor(user)

Adiciona o usuário à lista de editores da planilha ou do intervalo protegido. Esse método não dá automaticamente ao usuário permissão para editar a planilha. Para fazer isso, chame Spreadsheet.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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Adds the active user as an editor of the protected sheet.
sampleProtectedSheet.addEditor(Session.getActiveUser());

// Gets the editors of the protected sheet.
const editors = sampleProtectedSheet.getEditors();

// Logs the editors' email addresses to the console.
for (const editor of editors) {
  console.log(editor.getEmail());
}

Parâmetros

NomeTipoDescrição
userUserUma representação do usuário a ser adicionado.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

addEditors(emailAddresses)

Adiciona a matriz de usuários à lista de editores da planilha ou do intervalo protegido. Esse método não dá automaticamente aos usuários permissão para editar a planilha. Para fazer isso, chame Spreadsheet.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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Creates variables for the email addresses to add as editors.
// TODO(developer): Replace the email addresses with valid ones.
const TEST_EMAIL_1 = 'cloudysanfrancisco@gmail.com';
const TEST_EMAIL_2 = 'baklavainthebalkans@gmail.com';

// Protects the sheet.
const sampleProtectedSheet = 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.
const editors = sampleProtectedSheet.getEditors();

// Logs the editors' email addresses to the console.
for (const editor of editors) {
  console.log(editor.getEmail());
}

Parâmetros

NomeTipoDescrição
emailAddressesString[]Uma matriz de endereços de e-mail dos usuários a serem adicionados.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

addTargetAudience(audienceId)

Adiciona o público-alvo especificado como editor do intervalo protegido.

Parâmetros

NomeTipoDescrição
audienceIdStringO ID do público-alvo a ser adicionado.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

canDomainEdit()

Determina se todos os usuários no domínio que é proprietário da planilha têm permissão para editar a planilha ou o intervalo protegido. Gera uma exceção se o usuário não tiver permissão para editar a planilha ou o intervalo protegido. 

// 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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Logs whether domain users have permission to edit the protected sheet to the
// console.
console.log(sampleProtectedSheet.canDomainEdit());

Retornar

Boolean: true se todos os usuários no domínio que é proprietário da planilha têm permissão para editar o intervalo ou a página protegida; false, se não tiverem.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

canEdit()

Determina se o usuário tem permissão para editar a planilha ou o intervalo protegido. O proprietário da planilha sempre pode editar intervalos e páginas protegidas. 

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

Retornar

Boolean: true se o usuário tiver permissão para editar a página ou o intervalo protegido; false, caso contrário.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

getDescription()

Retorna a descrição do intervalo ou da página protegida. Se nenhuma descrição for definida, esse método vai retornar uma string vazia. 

// 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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet and sets the description.
const sampleProtectedSheet =
    sheet.protect().setDescription('Sample sheet is protected');

// Gets the description of the protected sheet and logs it to the console.
const sampleProtectedSheetDescription = sampleProtectedSheet.getDescription();
console.log(sampleProtectedSheetDescription);

Retornar

String: a descrição do intervalo ou da página protegida ou uma string vazia se nenhuma descrição tiver sido definida.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

getEditors()

Recebe a lista de editores do intervalo ou da página protegida. Gera uma exceção se o usuário não tiver permissão para editar a planilha ou o intervalo protegido. 

// Protect the active sheet, then remove all other users from the list of
// editors.
const sheet = SpreadsheetApp.getActiveSheet();
const 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.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

Retornar

User[]: uma matriz de usuários com permissão para editar o intervalo ou a página protegida.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

getProtectionType()

Recebe o tipo da área protegida, RANGE ou 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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Gets the type of the protected area.
const protectionType = sampleProtectedSheet.getProtectionType();

// Logs 'SHEET'to the console since the type of the protected area is a sheet.
console.log(protectionType.toString());

Retornar

ProtectionType: o tipo de área protegida, RANGE ou SHEET.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

getRange()

Recebe o intervalo que está sendo protegido. Se a proteção for aplicada à planilha em vez de um intervalo, esse método retornará um intervalo que abrange toda a planilha. 

// 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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range 'A1:B10' of Sheet1.
const range = sheet.getRange('A1:B10');

// Makes cells A1:B10 a protected range.
const sampleProtectedRange = range.protect();

// Gets the protected ranges on the sheet.
const protections = sheet.getProtections(SpreadsheetApp.ProtectionType.RANGE);

// Logs the A1 notation of the first protected range on the sheet.
console.log(protections[0].getRange().getA1Notation());

Retornar

Range: o intervalo que está sendo protegido.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

getRangeName()

Retorna o nome do intervalo protegido se ele estiver associado a um intervalo nomeado. Retorna null se a proteção não estiver associada a um intervalo nomeado. Os scripts precisam chamar setRangeName(rangeName) explicitamente para associar um intervalo protegido a um nomeado. Chamar Range.protect() para criar uma proteção de um Range que seja um intervalo nomeado, sem chamar setRangeName(rangeName), não é suficiente para associá-los. No entanto, a criação de um intervalo protegido a partir de um nomeado na interface das Planilhas Google os associa automaticamente. 

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

Retornar

String: o nome do intervalo nomeado protegido ou null se o intervalo protegido não estiver associado a um intervalo nomeado.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

getTargetAudiences()

Retorna os IDs dos públicos-alvo que podem editar o intervalo protegido.

Retornar

TargetAudience[]: uma matriz com os IDs dos públicos-alvo.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

getUnprotectedRanges()

Recebe uma matriz de intervalos não protegidos em uma página protegida. Se o objeto Protection corresponder a um intervalo protegido em vez de uma planilha protegida, esse método retornará uma matriz vazia. Para mudar os intervalos não protegidos, use setUnprotectedRanges(ranges) para definir uma nova matriz de intervalos. Para proteger novamente a planilha inteira, defina uma matriz vazia. 

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

Retornar

Range[]: uma matriz de intervalos não protegidos em uma página protegida

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

isWarningOnly()

Determina se a área protegida está usando a proteção "com base em avisos". A proteção baseada em avisos significa que todos os usuários podem editar dados na área, exceto quando a edição gera um aviso pedindo que o usuário confirme a edição. Por padrão, as planilhas ou intervalos protegidos não são baseados em avisos. Para mudar para o estado de aviso, use setWarningOnly(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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Sets the warning status for the protected sheet as true.
sampleProtectedSheet.setWarningOnly(true);

const protectedSheetWarningStatus = sampleProtectedSheet.isWarningOnly();

// Logs the warning status of the protected sheet to the console.
console.log(protectedSheetWarningStatus);

Retornar

Boolean: true se o intervalo ou a página protegida estiver usando apenas a proteção com base em avisos.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

remove()

Remove a proteção do intervalo ou da página. 

// Remove all range protections in the spreadsheet that the user has permission
// to edit.
const ss = SpreadsheetApp.getActive();
const protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (let i = 0; i < protections.length; i++) {
  const protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}
 
// Remove sheet protection from the active sheet, if the user has permission to
// edit it.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.getProtections(SpreadsheetApp.ProtectionType.SHEET)[0];
if (protection?.canEdit()) {
  protection.remove();
}

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

removeEditor(emailAddress)

Remove o usuário da lista de editores da planilha ou do intervalo protegido. Se o usuário for membro de um Grupo do Google com permissão de edição ou se todos os usuários no domínio tiverem permissão de edição, ele ainda poderá editar a área protegida. Não é possível remover o proprietário da planilha nem o usuário atual. 

// 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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Creates a variable for an email address.
// TODO(developer): Replace the email address with a valid one.
const TEST_EMAIL = 'baklavainthebalkans@gmail.com';

// Protects the sheet.
const sampleProtectedSheet = 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.
const editors = sampleProtectedSheet.getEditors();

// Logs the editors' email addresses to the console.
for (const editor of editors) {
  console.log(editor.getEmail());
}

Parâmetros

NomeTipoDescrição
emailAddressStringO endereço de e-mail do usuário a ser removido.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

removeEditor(user)

Remove o usuário da lista de editores da planilha ou do intervalo protegido. Se o usuário for membro de um grupo do Google com permissão de edição ou se todos os usuários do domínio tiverem essa permissão, ele ainda poderá editar a área protegida. Não é possível remover o proprietário da planilha nem o usuário atual. 

// 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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Removes the active user from the editors of the protected sheet.
sampleProtectedSheet.removeEditor(Session.getActiveUser());

// Gets the editors of the protected sheet.
const editors = sampleProtectedSheet.getEditors();

// Logs the editors' email addresses to the console.
for (const editor of editors) {
  console.log(editor.getEmail());
}

Parâmetros

NomeTipoDescrição
userUserUma representação do usuário a ser removido.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

removeEditors(emailAddresses)

Remove a matriz de usuários da lista de editores da planilha ou do intervalo protegido. Se algum dos usuários for membro de um Grupo do Google com permissão de edição ou se todos os usuários no domínio tiverem permissão de edição, eles ainda poderão editar a área protegida. Nem o proprietário da planilha nem o usuário atual podem ser removidos. 

// Protect the active sheet, then remove all other users from the list of
// editors.
const sheet = SpreadsheetApp.getActiveSheet();
const 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.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

Parâmetros

NomeTipoDescrição
emailAddressesString[]Uma matriz de endereços de e-mail dos usuários a serem removidos.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

removeTargetAudience(audienceId)

Remove o público-alvo especificado como editor do intervalo protegido.

Parâmetros

NomeTipoDescrição
audienceIdStringO ID do público-alvo a ser removido.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

setDescription(description)

Define a descrição do intervalo ou da página protegida. 

// 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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets the sheet 'Sheet1' by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet.
const sampleProtectedSheet = sheet.protect();

// Sets the sheet description to 'Sheet1 is protected.'
sampleProtectedSheet.setDescription('Sheet1 is protected');

// Gets the description of the protected sheet.
const sampleProtectedSheetDescription = sampleProtectedSheet.getDescription();

// Logs the description of the protected sheet to the console.
console.log(sampleProtectedSheetDescription);

Parâmetros

NomeTipoDescrição
descriptionStringA descrição do intervalo ou da página protegida.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

setDomainEdit(editable)

Define se todos os usuários no domínio que são proprietários da planilha têm permissão para editar a folha ou o intervalo protegido. Todos os usuários com permissão de edição explícita podem editar a área protegida, independentemente dessa configuração. Gera uma exceção se a planilha não pertencer a um domínio do Google Workspace, ou seja, se ela for de uma conta gmail.com.

Parâmetros

NomeTipoDescrição
editableBooleantrue se todos os usuários no domínio que é proprietário da planilha precisam ter permissão para editar o intervalo ou a planilha protegida; false, caso contrário.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

setNamedRange(namedRange)

Associa o intervalo protegido a um intervalo nomeado. Se o intervalo nomeado abranger uma área diferente do intervalo protegido atual, esse método moverá a proteção para abranger o intervalo nomeado. O intervalo nomeado precisa estar na mesma página que o intervalo protegido atual. Os scripts precisam chamar esse método explicitamente para associar um intervalo protegido a um nomeado. Chamar Range.protect() para criar uma proteção de um Range que seja um intervalo nomeado, sem chamar setRangeName(rangeName), não é suficiente para fazer a associação. No entanto, a criação de um intervalo protegido a partir de um nomeado na interface das Planilhas Google os associa automaticamente. 

// 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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Protects cells A1:D10 on Sheet1.
const sheet = ss.getSheetByName('Sheet1');
const protectedRange = 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.'
const newRange = sheet.getRange('E1:J10');
ss.setNamedRange('NewRange', newRange);
const namedRange = 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());

Parâmetros

NomeTipoDescrição
namedRangeNamedRangeO intervalo nomeado a ser associado ao intervalo protegido.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

setRange(range)

Ajusta o intervalo que está sendo protegido. Se o intervalo fornecido abranger uma área diferente do intervalo protegido atual, esse método moverá a proteção para abranger o novo intervalo. 

// 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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Protects cells A1:D10 on Sheet1 of the spreadsheet.
const sheet = ss.getSheetByName('Sheet1');
const protectedRange = 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.
const newRange = 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());

Parâmetros

NomeTipoDescrição
rangeRangeO novo intervalo a ser protegido contra edições.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

setRangeName(rangeName)

Associa o intervalo protegido a um intervalo nomeado. Se o intervalo nomeado abranger uma área diferente do intervalo protegido atual, esse método moverá a proteção para abranger o intervalo nomeado. O intervalo nomeado precisa estar na mesma página que o intervalo protegido atual. Os scripts precisam chamar esse método explicitamente para associar um intervalo protegido a um nomeado. Chamar Range.protect() para criar uma proteção de um Range que seja um intervalo nomeado, sem chamar setRangeName(rangeName), não é suficiente para fazer a associação. No entanto, a criação de um intervalo protegido a partir de um nomeado na interface das Planilhas Google os associa automaticamente. 

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

Parâmetros

NomeTipoDescrição
rangeNameStringO nome do intervalo nomeado a ser protegido.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

setUnprotectedRanges(ranges)

Remove a proteção de uma matriz de intervalos em uma página protegida. Gera uma exceção se o objeto Protection corresponder a um intervalo protegido em vez de uma página protegida ou se algum dos intervalos não estiver na página protegida. Para mudar os intervalos não protegidos, defina uma nova matriz de intervalos. Para proteger novamente a planilha inteira, defina uma matriz vazia. 

// Protect the active sheet except B2:C5, then remove all other users from the
// list of editors.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.protect().setDescription('Sample protected sheet');
const 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.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

Parâmetros

NomeTipoDescrição
rangesRange[]A matriz de intervalos que serão deixados desprotegidos em uma página protegida.

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

setWarningOnly(warningOnly)

Define se o intervalo protegido está usando ou não a proteção "com base em avisos". A proteção baseada em avisos significa que todos os usuários podem editar dados na área, exceto quando a edição gera um aviso pedindo que o usuário confirme a edição. Por padrão, as linhas ou planilhas protegidas não são baseadas em avisos. Para verificar o estado de aviso, use isWarningOnly(). 

// 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.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets the sheet 'Sheet1' by its name.
const sheet = ss.getSheetByName('Sheet1');

// Protects the sheet and sets the protection to warning-based.
const sampleProtectedSheet = sheet.protect().setWarningOnly(true);

// Logs whether the protected sheet is warning-based to the console.
console.log(sampleProtectedSheet.isWarningOnly());

Parâmetros

NomeTipoDescrição
warningOnlyBoolean

Retornar

Protection: o objeto que representa as configurações de proteção para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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