Objetos de evento

Com os gatilhos simples e instaláveis, o Apps Script pode executar uma função automaticamente se um determinado evento ocorrer. Quando um gatilho é acionado, o Apps Script transmite à função um objeto de evento como argumento, geralmente chamado de e. O objeto de evento contém informações sobre o contexto que causou o acionamento. Por exemplo, o código de amostra abaixo mostra um gatilho onEdit(e) simples para um script do Google Sheets que usa o objeto de evento para determinar qual célula foi editada.

function onEdit(e){
  // Set a comment on the edited cell to indicate when it was changed.
  var range = e.range;
  range.setNote('Last modified: ' + new Date());
}

Nesta página, detalhamos os campos no objeto de evento para diferentes tipos de acionadores.

Os eventos produzidos por acionadores instaláveis contêm um triggerUid que identifica o acionador que produziu o evento. Isso é útil para scripts que têm vários acionadores instaláveis.

Eventos das Planilhas Google

Os vários gatilhos específicos do Google Sheets permitem que os scripts respondam às ações de um usuário em uma planilha.

Abrir (simples e instalável)
authMode	Um valor da enumeração ScriptApp.AuthMode. LIMITED
source	Um objeto Spreadsheet que representa o arquivo do Google Sheets a que o script está vinculado. Spreadsheet
triggerUid	ID do gatilho que gerou este evento (somente gatilhos instaláveis). 4034124084959907503
user	Um objeto User, que representa o usuário ativo, se disponível (dependendo de um conjunto complexo de restrições de segurança). [e-mail]

Mudança (instalável)
authMode	Um valor da enumeração ScriptApp.AuthMode. FULL
changeType	O tipo de mudança (EDIT, INSERT_ROW, INSERT_COLUMN, REMOVE_ROW, REMOVE_COLUMN, INSERT_GRID, REMOVE_GRID, FORMAT ou OTHER). INSERT_ROW
source	Um objeto Spreadsheet que representa o arquivo das Planilhas Google a que o script está vinculado. Spreadsheet
triggerUid	ID do gatilho que gerou este evento. 4034124084959907503
user	Um objeto User, que representa o usuário ativo, se disponível (dependendo de um conjunto complexo de restrições de segurança). [e-mail]

Editar (simples e instalável)
authMode	Um valor da enumeração ScriptApp.AuthMode. LIMITED
oldValue	Valor da célula antes da edição, se houver. Disponível apenas se o intervalo editado for uma única célula. Será indefinido se a célula não tiver conteúdo anterior. 1234
range	Um objeto Range, que representa a célula ou o intervalo de células editadas. Range
source	Um objeto Spreadsheet que representa o arquivo do Google Sheets a que o script está vinculado. Spreadsheet
triggerUid	ID do gatilho que gerou este evento (somente gatilhos instaláveis). 4034124084959907503
user	Um objeto User, que representa o usuário ativo, se disponível (dependendo de um conjunto complexo de restrições de segurança). [e-mail]
value	Novo valor da célula após a edição. Disponível apenas se o intervalo editado for uma única célula. 10

Envio de formulário (instalável)
Cuidado:use esse acionador de envio de formulário com SpreadsheetTriggerBuilder.
authMode	Um valor da enumeração ScriptApp.AuthMode. FULL
namedValues	Um objeto que contém os nomes e valores das perguntas do envio do formulário. { 'First Name': ['Jane'], 'Timestamp': ['6/7/2015 20:54:13'], 'Last Name': ['Doe'] }
range	Um objeto Range, que representa a célula ou o intervalo de células editadas. Range
triggerUid	ID do gatilho que gerou este evento. 4034124084959907503
values	Matriz com valores na mesma ordem em que aparecem na planilha. ['2015/05/04 15:00', '[e-mail]', 'Bob', '27', 'Bill', '28', 'Susan', '25']

Eventos do Documentos Google

Os gatilhos permitem que o Google Docs responda quando um usuário abre um documento.

Abrir (simples e instalável)
authMode	Um valor da enumeração ScriptApp.AuthMode. LIMITED
source	Um objeto Document que representa o arquivo do Google Docs a que o script está vinculado. Document
triggerUid	ID do gatilho que gerou este evento (somente gatilhos instaláveis). 4034124084959907503
user	Um objeto User, que representa o usuário ativo, se disponível (dependendo de um conjunto complexo de restrições de segurança). [e-mail]

Eventos do Apresentações Google

Os gatilhos permitem que as Apresentações Google respondam quando um usuário abre uma apresentação.

Abrir (simples)
authMode	Um valor da enumeração ScriptApp.AuthMode. LIMITED
source	Um objeto Presentation que representa o arquivo do Google Apresentações a que o script está vinculado. Presentation
user	Um objeto User, que representa o usuário ativo, se disponível (dependendo de um conjunto complexo de restrições de segurança). [e-mail]

Eventos dos Formulários Google

Os gatilhos específicos dos Formulários Google permitem que os scripts respondam quando um usuário edita um formulário ou envia uma resposta.

Abrir * (simples e instalável)
authMode	Um valor da enumeração ScriptApp.AuthMode. LIMITED
source	Um objeto Form, que representa o arquivo do Google Formulários a que o script está vinculado. Form
triggerUid	ID do gatilho que gerou este evento (somente gatilhos instaláveis). 4034124084959907503
user	Um objeto User, que representa o usuário ativo, se disponível (dependendo de um conjunto complexo de restrições de segurança). [e-mail]

* Esse evento não ocorre quando um usuário abre um formulário para responder, mas sim quando um editor abre o formulário para modificá-lo.

Envio de formulário (instalável)
Cuidado:use esse acionador de envio de formulário com FormTriggerBuilder.
authMode	Um valor da enumeração ScriptApp.AuthMode. FULL
response	Um objeto FormResponse, que representa a resposta do usuário ao formulário como um todo. FormResponse
source	Um objeto Form, que representa o arquivo do Google Formulários a que o script está vinculado. Form
triggerUid	ID do gatilho que gerou este evento. 4034124084959907503

Eventos do Google Agenda

Os gatilhos do Google Agenda são acionados quando os eventos da agenda de um usuário são atualizados (criados, editados ou excluídos).

Esses acionadores não informam qual evento mudou ou como ele mudou. Em vez disso, eles indicam que seu código precisa fazer uma operação de sincronização incremental para capturar as mudanças recentes na agenda. Para uma descrição completa desse procedimento, consulte o guia de sincronização de recursos da API Calendar.

Para sincronizar com o Google Agenda no Apps Script, siga estas etapas:

1. Ative o serviço avançado do Google Agenda para o projeto de script. O serviço do Google Agenda integrado não é suficiente para esse fluxo de trabalho.
2. Determine quais agendas devem ser sincronizadas. Para cada agenda, faça uma operação de sincronização inicial usando o método Events.list() do serviço avançado do Google Agenda.
3. O resultado da sincronização inicial retorna um nextSyncToken para essa agenda. Salve esse token para uso posterior.
4. Quando o gatilho EventUpdated do Apps Script é acionado, indicando uma mudança no evento da agenda, realize uma sincronização incremental para a agenda afetada usando o nextSyncToken armazenado. Essa é essencialmente outra solicitação Events.list(), mas fornecer o nextSyncToken limita a resposta apenas aos eventos que mudaram desde a última sincronização.
5. Examine a resposta da sincronização para saber quais eventos foram atualizados e faça com que seu código responda adequadamente. Por exemplo, é possível registrar a mudança, atualizar uma planilha, enviar avisos por e-mail ou realizar outras ações.
6. Atualize o nextSyncToken armazenado para esse calendário com o que foi retornado pela solicitação de sincronização incremental. Isso força a próxima operação de sincronização a retornar apenas as mudanças mais recentes.

Atenção: às vezes, os tokens de sincronização são invalidados pelo servidor, resultando em um erro 410. Quando isso acontecer, seu código vai realizar uma sincronização completa e substituir todos os dados e tokens sincronizados armazenados para essa agenda.

EventUpdated (instalável)
authMode	Um valor da enumeração ScriptApp.AuthMode. FULL
calendarId	O ID de string da agenda em que a atualização do evento ocorreu. [e-mail]
triggerUid	ID do gatilho que gerou este evento. 4034124084959907503

Eventos de complementos do Google Workspace

O gatilho onInstall() é executado automaticamente quando um usuário instala um complemento.

Instalar (simples)
authMode	Um valor da enumeração ScriptApp.AuthMode. FULL

Eventos do app Google Chat

Para saber mais sobre objetos de evento no Google Chat, consulte Receber e responder a interações com seu app do Google Chat.

Eventos baseados em tempo

Os gatilhos por tempo (também chamados de gatilhos de relógio) permitem que os scripts sejam executados em um horário específico ou em um intervalo recorrente.

Baseado no tempo (instalável)
authMode	Um valor da enumeração ScriptApp.AuthMode. FULL
day-of-month	Entre 1 e 31. Como esse nome de propriedade contém traços, ele precisa ser acessado por e['day-of-month'] em vez da notação de ponto. 31
day-of-week	Entre 1 (segunda-feira) e 7 (domingo). Como esse nome de propriedade contém traços, ele precisa ser acessado por e['day-of-week'] em vez da notação de ponto. 7
hour	Entre 0 e 23. 23
minute	Entre 0 e 59. 59
month	Entre 1 e 12. 12
second	Entre 0 e 59. 59
timezone	O fuso horário. UTC
triggerUid	ID do gatilho que gerou este evento. 4034124084959907503
week-of-year	Entre 1 e 52. Como esse nome de propriedade contém traços, ele precisa ser acessado por e['week-of-year'] em vez da notação de ponto. 52
year	O ano. 2015