Class ScriptApp

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

Acesse e manipule a publicação e o acionamento de scripts. Essa classe permite que os usuários criem acionadores de script e controlem a publicação do script como um serviço.

Propriedades

PropriedadeTipoDescrição
AuthModeAuthModeUma enumeração que identifica as categorias de serviços autorizados que o Apps Script pode executar usando uma função acionada.
AuthorizationStatusAuthorizationStatusUma enumeração que indica o status de autorização de um script.
EventTypeEventTypeUma enumeração que indica o tipo de evento acionado.
InstallationSourceInstallationSourceUma enumeração que indica como o script foi instalado para o usuário como um complemento.
TriggerSourceTriggerSourceUma enumeração que indica a origem do evento que faz com que o acionador seja disparado.
WeekDayWeekdayUma enumeração que representa os dias da semana.

Métodos

MétodoTipo de retornoBreve descrição
deleteTrigger(trigger)voidRemove o gatilho determinado para que ele não seja mais executado.
getAuthorizationInfo(authMode)AuthorizationInfoRecebe um objeto usado para determinar se o usuário precisa autorizar esse script a usar um ou mais serviços e fornecer o URL para uma caixa de diálogo de autorização.
getIdentityToken()StringRecebe um token de identidade do OpenID Connect para o usuário efetivo, se o escopo openid tiver sido concedido.
getInstallationSource()InstallationSourceRetorna um valor enum que indica como o script foi instalado como um complemento para o usuário atual, por exemplo, se o usuário o instalou pessoalmente pela Chrome Web Store ou se um administrador do domínio o instalou para todos os usuários.
getOAuthToken()StringRecebe o token de acesso do OAuth 2.0 do usuário efetivo.
getProjectTriggers()Trigger[]Recebe todos os gatilhos instaláveis associados ao projeto atual e ao usuário atual.
getScriptId()StringRecebe o ID exclusivo do projeto de script.
getService()ServiceRecebe um objeto usado para controlar a publicação do script como um app da Web.
getUserTriggers(document)Trigger[]Recebe todos os acionadores instaláveis por este usuário no documento especificado, somente para este script ou o complemento.
getUserTriggers(form)Trigger[]Recebe todos os acionadores instaláveis por este usuário no formulário fornecido, apenas para este script ou complemento.
getUserTriggers(spreadsheet)Trigger[]Recebe todos os acionadores instaláveis por este usuário na planilha especificada, para este script ou apenas um complemento.
invalidateAuth()voidInvalida a autorização que o usuário efetivo tem para executar o script atual.
newStateToken()StateTokenBuilderCria um builder para um token de estado que pode ser usado em uma API de callback (como um fluxo de OAuth).
newTrigger(functionName)TriggerBuilderComeça o processo de criação de um gatilho instalável que, quando acionado, chama uma determinada função.

Documentação detalhada

deleteTrigger(trigger)

Remove o gatilho determinado para que ele não seja mais executado.

// Deletes all triggers in the current project.
var triggers = ScriptApp.getProjectTriggers();
for (var i = 0; i < triggers.length; i++) {
  ScriptApp.deleteTrigger(triggers[i]);
}

Parâmetros

NomeTipoDescrição
triggerTriggerAcionador a ser excluído.

Autorização

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

  • https://www.googleapis.com/auth/script.scriptapp

getAuthorizationInfo(authMode)

Recebe um objeto usado para determinar se o usuário precisa autorizar esse script a usar um ou mais serviços e fornecer o URL para uma caixa de diálogo de autorização. Se o script for publicado como um complemento que usa acionadores instaláveis, essas informações poderão ser usadas para controlar o acesso a seções de código para as quais o usuário não tem a autorização necessária. Como alternativa, o complemento pode pedir que o usuário abra o URL da caixa de diálogo de autorização para resolver o problema.

var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
status = authInfo.getAuthorizationStatus();
url = authInfo.getAuthorizationUrl();

Parâmetros

NomeTipoDescrição
authModeAuthModeo modo de autorização para que as informações de autorização são solicitadas. Em quase todos os casos, o valor de authMode precisa ser ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL), já que nenhum outro modo de autorização exige que os usuários concedam autorização

Retornar

AuthorizationInfo: um objeto que pode fornecer informações sobre o status de autorização do usuário


getIdentityToken()

Recebe um token de identidade do OpenID Connect para o usuário efetivo, se o escopo openid tiver sido concedido. Esse escopo não é incluído por padrão. É necessário adicioná-lo como um escopo explícito no arquivo de manifesto para o solicitar. Inclua os escopos https://www.googleapis.com/auth/userinfo.email ou https://www.googleapis.com/auth/userinfo.profile para retornar mais informações do usuário no token.

O token de ID retornado é um Token da Web JSON (JWT, na sigla em inglês) codificado e precisa ser decodificado para extrair informações dele. Os exemplos a seguir mostram como decodificar o token e extrair o ID do perfil do Google eficaz do usuário.

var idToken = ScriptApp.getIdentityToken();
var body = idToken.split('.')[1];
var decoded = Utilities.newBlob(Utilities.base64Decode(body)).getDataAsString();
var payload = JSON.parse(decoded);
var profileId = payload.sub;
Logger.log('Profile ID: ' + profileId);
Consulte a documentação do OpenID Connect para ver a lista completa de campos (reivindicações) retornados.

Retornar

String: o token de identidade, se disponível. Caso contrário, null.


getInstallationSource()

Retorna um valor enum que indica como o script foi instalado como um complemento para o usuário atual, por exemplo, se o usuário o instalou pessoalmente pela Chrome Web Store ou se um administrador do domínio o instalou para todos os usuários.

Retornar

InstallationSource: a fonte da instalação.


getOAuthToken()

Recebe o token de acesso do OAuth 2.0 do usuário efetivo. Se os escopos de OAuth do script forem suficientes para autorizar outra API do Google que normalmente precisa de um fluxo de OAuth próprio (como o Google Picker), os scripts podem ignorar o segundo prompt de autorização passando esse token. O token expira após um período (alguns minutos, no mínimo). Os scripts precisam lidar com falhas de autorização e chamar esse método para receber um novo token quando necessário.

O token retornado por esse método inclui apenas escopos que o script precisa atualmente. Os escopos que foram autorizados anteriormente, mas que não são mais usados pelo script, não são incluídos no token retornado. Se outros escopos de OAuth forem necessários além do que o script exige, eles poderão ser especificados no arquivo de manifesto do script.

Retornar

String: uma representação de string do token OAuth 2.0.


getProjectTriggers()

Recebe todos os gatilhos instaláveis associados ao projeto atual e ao usuário atual.

Logger.log('Current project has ' + ScriptApp.getProjectTriggers().length + ' triggers.');

Retornar

Trigger[]: uma matriz dos gatilhos atuais do usuário associado a este projeto.

Autorização

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

  • https://www.googleapis.com/auth/script.scriptapp

getScriptId()

Recebe o ID exclusivo do projeto de script. Esse é o método preferencial para receber o identificador exclusivo do projeto de script em vez de getProjectKey(). Esse ID pode ser usado em todos os locais em que a chave do projeto foi fornecida anteriormente.

Retornar

String: o ID do projeto do script.


getService()

Recebe um objeto usado para controlar a publicação do script como um app da Web.

// Get the URL of the published web app.
var url = ScriptApp.getService().getUrl();

Retornar

Service: um objeto usado para observar e controlar a publicação do script como um app da Web.


getUserTriggers(document)

Recebe todos os acionadores instaláveis por este usuário no documento especificado, somente para este script ou o complemento. Esse método não pode ser usado para ver os acionadores anexados a outros scripts.

var doc = DocumentApp.getActiveDocument();
var triggers = ScriptApp.getUserTriggers(doc);
// Log the handler function for the first trigger in the array.
Logger.log(triggers[0].getHandlerFunction());

Parâmetros

NomeTipoDescrição
documentDocumentUm arquivo do Documentos Google que talvez contenha acionadores instaláveis.

Retornar

Trigger[]: uma matriz de acionadores que pertencem a este usuário no documento especificado.

Autorização

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

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(form)

Recebe todos os acionadores instaláveis por este usuário no formulário fornecido, apenas para este script ou complemento. Esse método não pode ser usado para ver os acionadores anexados a outros scripts.

var form = FormApp.getActiveForm();
var triggers = ScriptApp.getUserTriggers(form);
// Log the trigger source for the first trigger in the array.
Logger.log(triggers[0].getTriggerSource());

Parâmetros

NomeTipoDescrição
formFormUm arquivo do Formulários Google que talvez contenha acionadores instaláveis.

Retornar

Trigger[]: uma matriz de acionadores que pertencem a este usuário no formulário especificado.

Autorização

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

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(spreadsheet)

Recebe todos os acionadores instaláveis por este usuário na planilha especificada, para este script ou apenas um complemento. Esse método não pode ser usado para ver os acionadores anexados a outros scripts.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var triggers = ScriptApp.getUserTriggers(ss);
// Log the event type for the first trigger in the array.
Logger.log(triggers[0].getEventType());

Parâmetros

NomeTipoDescrição
spreadsheetSpreadsheetUm arquivo do Planilhas Google que talvez contenha acionadores instaláveis.

Retornar

Trigger[]: uma matriz de acionadores que pertencem a este usuário na planilha especificada.

Autorização

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

  • https://www.googleapis.com/auth/script.scriptapp

invalidateAuth()

Invalida a autorização que o usuário efetivo tem para executar o script atual. Utilizado para invalidar as permissões do script atual. Isso é útil principalmente para funções marcadas como autorização única. Como as funções de autorização única não podem ser chamadas na primeira execução depois que o script adquirir a autorização, se você quiser realizar uma ação depois, será necessário revogar todas as autorizações que o script tinha. Assim, o usuário poderá ver a caixa de diálogo de autorização novamente.

ScriptApp.invalidateAuth();

Gera

Error: quando a invalidação falha


newStateToken()

Cria um builder para um token de estado que pode ser usado em uma API de callback (como um fluxo de OAuth).

// Generate a callback URL, given the name of a callback function. The script does not need to
// be published as a web app; the /usercallback URL suffix replaces /edit in any script's URL.
function getCallbackURL(callbackFunction) {
  // IMPORTANT: Replace string below with the URL from your script, minus the /edit at the end.
  var scriptUrl = 'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  var urlSuffix = '/usercallback?state=';
  var stateToken = ScriptApp.newStateToken()
      .withMethod(callbackFunction)
      .withTimeout(120)
      .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

Na maioria dos fluxos do OAuth2, o token state é transmitido diretamente para o endpoint de autorização (não como parte do URL de callback), e o endpoint de autorização o transmite como parte do URL de callback.

Exemplo:

  • O script redireciona o usuário para o URL de autorização do OAuth2: https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters
  • O usuário clica em"Autorizar"e a página de autorização do OAuth2 redireciona o usuário de volta para https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
  • O redirecionamento acima (de volta para http://script.google.com/...) faz com que a solicitação do navegador para /usercallback, que invoca o método especificado por StateTokenBuilder.withMethod(method).

Retornar

StateTokenBuilder: um objeto usado para continuar o processo de criação de token de estado.


newTrigger(functionName)

Começa o processo de criação de um gatilho instalável que, quando acionado, chama uma determinada função.

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

Parâmetros

NomeTipoDescrição
functionNameStringA função a ser chamada quando o acionador é disparado. É possível usar funções de bibliotecas incluídas, como Library.libFunction1.

Retornar

TriggerBuilder: um objeto usado para continuar o processo de criação de gatilho.

Autorização

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

  • https://www.googleapis.com/auth/script.scriptapp

Métodos obsoletos