Class Protection

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.
Proteção

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

// 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);
}

Métodos

MétodoTipo de retornoBreve descrição
addEditor(emailAddress)ProtectionAdiciona o usuário fornecido à lista de editores da página ou ao intervalo protegido.
addEditor(user)ProtectionAdiciona o usuário fornecido à lista de editores da página ou ao intervalo protegido.
addEditors(emailAddresses)ProtectionAdiciona a matriz especificada de usuários à lista de editores para a página ou o intervalo protegido.
addTargetAudience(audienceId)ProtectionAdiciona o público-alvo especificado como um editor do intervalo protegido.
canDomainEdit()BooleanDetermina se todos os usuários no domínio proprietário da planilha têm permissão para editar o intervalo ou a página protegida.
canEdit()BooleanDetermina se o usuário tem permissão para editar o intervalo ou a página protegida.
getDescription()StringRecebe 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()StringAcessa o nome do intervalo protegido se 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()voidDesprotege o intervalo ou a página.
removeEditor(emailAddress)ProtectionRemove o usuário especificado da lista de editores da página ou do intervalo protegido.
removeEditor(user)ProtectionRemove o usuário especificado da lista de editores da página ou do intervalo protegido.
removeEditors(emailAddresses)ProtectionRemove a matriz de usuários especificada da lista de editores da página ou do intervalo protegido.
removeTargetAudience(audienceId)ProtectionRemove o público-alvo especificado como um 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 proprietário da planilha têm permissão para editar o intervalo ou a página protegida.
setNamedRange(namedRange)ProtectionAssocia o intervalo protegido a um intervalo nomeado existente.
setRange(range)ProtectionAjusta o intervalo que está sendo protegido.
setRangeName(rangeName)ProtectionAssocia o intervalo protegido a um intervalo nomeado existente.
setUnprotectedRanges(ranges)ProtectionNão protege a matriz especificada de intervalos em uma página protegida.
setWarningOnly(warningOnly)ProtectionDefine se este intervalo protegido está ou não usando a proteção de "com base em avisos"

Documentação detalhada

addEditor(emailAddress)

Adiciona o usuário fornecido à lista de editores da página ou ao 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).

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 o 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 fornecido à lista de editores da página ou ao 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).

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 o 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 especificada de usuários à lista de editores para a página ou o intervalo protegido. Esse método não dá automaticamente aos usuários permissão para editar a planilha em si. Para fazer isso, chame Spreadsheet.addEditors(emailAddresses).

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 o 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 um 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 proprietário da planilha têm permissão para editar o intervalo ou a página protegida. Lança uma exceção se o usuário não tiver permissão para editar o intervalo protegido ou a página.

Retornar

Boolean: true se todos os usuários no domínio que pertencem à planilha tiverem permissão para editar o intervalo ou a página protegida. false se não forem

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 o intervalo ou a página protegida. O proprietário da planilha sempre pode editar intervalos e páginas protegidos.

// 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();
  }
}

Retornar

Boolean: true se o usuário tiver permissão para editar o intervalo ou a página protegida. false se não tiver

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()

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

Retornar

String: a descrição do intervalo ou da página protegida, ou uma string vazia se nenhuma descrição for 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. Lança uma exceção se o usuário não tiver permissão para editar o intervalo ou a página protegida.

// 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);
}

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.

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 à página em vez de um intervalo, esse método retornará um intervalo que abrange toda a página.

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()

Acessa o nome do intervalo protegido se estiver associado a um intervalo nomeado. Retornará null se a proteção não estiver associada a um intervalo nomeado. Os scripts precisam chamar explicitamente setRangeName(rangeName) para associar um intervalo protegido a um intervalo 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á-lo. No entanto, a criação de um intervalo protegido a partir de um intervalo nomeado na IU do Planilhas Google o associa automaticamente.

// 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.

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 de IDs de 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 página protegida, esse método retornará uma matriz vazia. Para mudar os intervalos desprotegidos, use setUnprotectedRanges(ranges) para definir uma nova matriz de intervalos. Para proteger novamente a página inteira, defina uma matriz vazia.

// 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);

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 com base em alertas significa que todos os usuários podem editar dados na área, exceto a edição que solicita um aviso solicitando que o usuário confirme a edição. Por padrão, os intervalos ou páginas protegidos não são baseados em alertas. Para mudar para o estado de aviso, use setWarningOnly(warningOnly).

Retornar

Booleantrue se o intervalo protegido ou a página estiverem usando somente proteção com base em alertas

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()

Desprotege o intervalo ou a página.

// 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();
}

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 especificado da lista de editores da página ou do intervalo protegido. Se o usuário for membro de um Grupo do Google com permissão para edição ou se todos os usuários do domínio tiverem permissão para edição, o usuário ainda poderá editar a área protegida. Não é possível remover o proprietário da planilha nem o usuário atual.

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 o 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 especificado da lista de editores da página ou do intervalo protegido. Se o usuário for membro de um grupo do Google com permissão para edição ou se todos os usuários no domínio tiverem permissão para edição, o usuário também poderá editar a área protegida. Não é possível remover o proprietário da planilha nem o usuário atual.

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 o 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 especificada da lista de editores da página ou do intervalo protegido. Se algum dos usuários for membro de um grupo do Google com permissão para edição ou se todos os usuários do domínio tiverem permissão para edição, esses usuários ainda poderão editar a área protegida. Não é possível remover o proprietário da planilha nem o usuário atual.

// 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);
}

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 o 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 um 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.

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 proprietário da planilha têm permissão para editar o intervalo ou a página protegida. Qualquer usuário que tenha permissão explícita para edição pode editar a área protegida, independentemente dessa configuração. Gera uma exceção se a planilha não pertence a um domínio do Google Workspace (ou seja, se for de propriedade de uma conta do gmail.com).

Parâmetros

NomeTipoDescrição
editableBooleantrue se todos os usuários no domínio que tiverem a planilha precisarem ter permissão para editar o intervalo ou a página protegida. false em caso negativo.

Retornar

Protection: o objeto que representa as configurações de proteção, para o 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 existente. Se o intervalo nomeado cobrir uma área diferente do intervalo protegido atual, esse método vai mover a proteção para cobrir 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 intervalo 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á-lo. No entanto, a criação de um intervalo protegido a partir de um intervalo nomeado na IU do Planilhas Google o associa automaticamente.

Parâmetros

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

Retornar

Protection: o objeto que representa as configurações de proteção, para o 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 especificado cobrir uma área diferente do intervalo protegido atual, esse método vai mover a proteção para cobrir o novo intervalo.

Parâmetros

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

Retornar

Protection: o objeto que representa as configurações de proteção, para o 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 existente. Se o intervalo nomeado cobrir uma área diferente do intervalo protegido atual, esse método vai mover a proteção para cobrir 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 intervalo 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á-lo. No entanto, a criação de um intervalo protegido a partir de um intervalo nomeado na IU do Planilhas Google o associa automaticamente.

// 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.

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 o 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)

Não protege a matriz especificada de intervalos em uma página protegida. Uma exceção será gerada se o objeto Protection corresponder a um intervalo protegido em vez de uma página protegida ou se qualquer um dos intervalos não estiver na página protegida. Para alterar os intervalos desprotegidos, defina uma nova matriz de intervalos. Para proteger novamente a página inteira, defina uma matriz vazia.

// 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);
}

Parâmetros

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

Retornar

Protection: o objeto que representa as configurações de proteção, para o 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 este intervalo protegido está ou não usando a proteção de "com base em avisos" Com a proteção baseada em um aviso, todos os usuários podem editar dados na área, exceto quando a edição solicita um aviso pedindo que o usuário confirme a edição. Por padrão, os intervalos ou páginas protegidos não são baseados em avisos. Para verificar o estado do alerta, use 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