Class ScriptApp

ScriptApp

Acessar e manipular a publicação de scripts e gatilhos. Esta classe permite que os usuários criem scripts aciona e controla a publicação do script como serviço.

Propriedades

PropriedadeTipoDescrição
AuthModeAuthModeUma enumeração que identifica as categorias de serviços autorizados que o Apps Script pode com 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 acionador fornecido para que ele não seja mais executado.
getAuthorizationInfo(authMode)AuthorizationInfoExtrai um objeto usado para determinar se o usuário precisa autorizar este script a usar um ou 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 de enumeração que indica como o script foi instalado como um complemento do do usuário atual (por exemplo, se ele instalou o aplicativo pessoalmente na Chrome Web Store, por exemplo) Store ou se um administrador de domínio o instalou para todos os usuários).
getOAuthToken()StringRecebe o acesso ao OAuth 2.0 token para o usuário em vigor.
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 que pertencem a este usuário no documento especificado para este script ou como complemento.
getUserTriggers(form)Trigger[]Recebe todos os acionadores instaláveis pertencentes a este usuário no formulário especificado para este script ou complemento .
getUserTriggers(spreadsheet)Trigger[]Recebe todos os acionadores instaláveis que pertencem a este usuário na planilha especificada para este script ou como 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 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 acionador fornecido 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
triggerTriggerO gatilho a ser excluído.

Autorização

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

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

getAuthorizationInfo(authMode)

Extrai um objeto usado para determinar se o usuário precisa autorizar este script a usar um ou 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 gatilhos instaláveis, essas informações podem ser usado para controlar o acesso a seções de código para as quais o usuário não tem as informações necessárias autorização. Alternativamente, o complemento pode solicitar que o usuário abra o URL para a 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 o qual as informações de autorização são solicitadas; no 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. Este escopo não está incluído por padrão, e é necessário adicioná-lo como um escopo explícito no manifesto para solicitá-lo. Inclua os escopos https://www.googleapis.com/auth/userinfo.email ou https://www.googleapis.com/auth/userinfo.profile para retornar outros informações do usuário no token.

O token de ID retornado é um JSON Web Token (JWT) codificado. ele 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 do usuário em vigor.

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 o OpenID Connect. documentação para obter a lista completa de campos (declarações) retornados.

Retornar

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


getInstallationSource()

Retorna um valor de enumeração que indica como o script foi instalado como um complemento do do usuário atual (por exemplo, se ele instalou o aplicativo pessoalmente na Chrome Web Store, por exemplo) Store ou se um administrador de domínio o instalou para todos os usuários).

Retornar

InstallationSource: a fonte da instalação.


getOAuthToken()

Recebe o acesso ao OAuth 2.0 token para o usuário em vigor. Se os escopos OAuth do script forem suficientes para autorizar outra API do Google que normalmente requer um fluxo OAuth próprio (como o Seletor do Google), os scripts podem ignorar o ao segundo prompt de autorização passando esse token. O token expira depois de um tempo (um alguns minutos, no mínimo); scripts devem lidar com falhas de autorização e chamar esse método para para receber um novo token quando necessário.

O token retornado por esse método inclui apenas os escopos necessários no momento. Os escopos que foram autorizados anteriormente, mas não são mais usados pelo script, não estão incluídos nos o token retornado. Se forem necessários escopos OAuth adicionais além do que o próprio script exigir, eles podem ser especificados no script arquivo de manifesto do app.

Retornar

String: uma representação em 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 do usuário atual associados ao projeto.

Autorização

Os scripts que usam esse método precisam de 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 recomendado para conseguir o identificador exclusivo para o projeto de script, em vez de getProjectKey(). Este ID pode ser usado em todos os lugares em que a chave do projeto foi fornecida anteriormente.

Retornar

String: o ID do projeto de 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 que pertencem a este usuário no documento especificado para este script ou como complemento. Não é possível usar esse método 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 pode conter acionadores instaláveis.

Retornar

Trigger[]: uma matriz de acionadores pertencentes a esse usuário em um determinado documento.

Autorização

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

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

getUserTriggers(form)

Recebe todos os acionadores instaláveis pertencentes a este usuário no formulário especificado para este script ou complemento . Não é possível usar esse método 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 pode conter acionadores instaláveis.

Retornar

Trigger[]: uma matriz de acionadores pertencentes a esse usuário no formato fornecido.

Autorização

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

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

getUserTriggers(spreadsheet)

Recebe todos os acionadores instaláveis que pertencem a este usuário na planilha especificada para este script ou como complemento. Não é possível usar esse método 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 das Planilhas Google que pode conter acionadores instaláveis.

Retornar

Trigger[]: uma matriz de acionadores pertencentes a esse usuário na planilha especificada.

Autorização

Os scripts que usam esse método precisam de 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. Usado para invalidará todas as permissões para o script atual. Isso é especialmente útil para funções e é marcada como autorização one-shot. Como as funções de autorização única só podem ser chamadas de ser executado pela primeira vez depois que o script tiver a autorização, se você quiser realizar uma ação depois, é necessário revogar qualquer autorização que o script tenha para que o usuário possa ver o 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 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 de OAuth2, o token state é transmitido para o endpoint de autorização diretamente (não como parte do URL de callback), e o endpoint de autorização a passa como parte do URL de retorno de chamada.

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 a http://script.google.com/...) faz com que o navegador solicitação para /usercallback, que invoca o método especificado por StateTokenBuilder.withMethod(method).

Retornar

StateTokenBuilder: um objeto usado para continuar o processo de criação do 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 for 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 do acionador.

Autorização

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

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

Métodos obsoletos