Objetos de evento

Os gatilhos simples e os instaláveis permitem que o Apps Script execute uma função automaticamente quando um determinado evento ocorre. Quando um acionador é acionado, o Apps Script transmite à função um objeto de evento como um argumento, normalmente chamado de e. O objeto de evento contém informações sobre o contexto que acionou o gatilho. Por exemplo, o código de exemplo abaixo mostra um acionador onEdit(e) simples para um script das Planilhas Google 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());
}

Esta página detalha os campos no objeto de evento para diferentes tipos de acionadores.

Eventos das Planilhas Google

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

Abrir

(simples e pode ser instalado)
authMode

Um valor da enumeração ScriptApp.AuthMode.

LIMITED
source

Um objeto Spreadsheet, que representa o arquivo do Google Planilhas ao qual o script está vinculado.

Spreadsheet
triggerUid

ID do gatilho que produziu esse 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).

amin@example.com

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 ao qual o script está vinculado.

Spreadsheet
triggerUid

ID do acionador que produziu esse 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).

amin@example.com

Editar

(simples e pode ser instalado)
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 que foram editados.

Range
source

Um objeto Spreadsheet, que representa o arquivo do Google Planilhas ao qual o script está vinculado.

Spreadsheet
triggerUid

ID do gatilho que produziu esse 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).

amin@example.com
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)
authMode

Um valor da enumeração ScriptApp.AuthMode.

FULL
namedValues

Um objeto que contém os nomes e os 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 que foram editados.

Range
triggerUid

ID do acionador que produziu esse evento.

4034124084959907503
values

Matriz com valores na mesma ordem em que aparecem na planilha.

['2015/05/04 15:00', 'amin@example.com', 'Bob', '27', 'Bill',
'28', 'Susan', '25']

Eventos do Documentos Google

Os acionadores permitem que os Documentos do Google respondam quando um usuário abre um documento.

Abrir

(simples e pode ser instalado)
authMode

Um valor da enumeração ScriptApp.AuthMode.

LIMITED
source

Um objeto Document, que representa o arquivo do Google Docs ao qual o script está vinculado.

Document
triggerUid

ID do gatilho que produziu esse 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).

amin@example.com

Eventos do Apresentações Google

Os acionadores permitem que o Apresentações Google responda 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 Slides ao qual 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).

amin@example.com

Eventos dos Formulários Google

Os acionadores 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 Forms ao qual o script está vinculado.

Form
triggerUid

ID do gatilho que produziu esse 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).

amin@example.com

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

Envio de formulário

(instalável)
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 Forms ao qual o script está vinculado.

Form
triggerUid

ID do acionador que produziu esse evento.

4034124084959907503

Eventos do Google Agenda

Os gatilhos da 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 o código precisa fazer uma operação de sincronização incremental para detectar as mudanças recentes na agenda. Para uma descrição completa deste procedimento, consulte o guia de sincronização de recursos da API Calendar.

Para sincronizar com o 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 de agenda integrado não é suficiente para esse fluxo de trabalho.
  2. Determine quais agendas devem ser sincronizadas. Para cada uma dessas agendas, faça uma operação de sincronização inicial usando o método Events.list() do serviço avançado do Agenda.
  3. O resultado da sincronização inicial retorna um nextSyncToken para essa agenda. Armazene esse token para uso posterior.
  4. Quando o acionador EventUpdated do Apps Script é acionado indicando uma mudança de evento de calendário, realize uma sincronização incremental para o calendário afetado usando o nextSyncToken armazenado. Essa é essencialmente outra solicitação Events.list(), mas fornecer 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 o código responda de maneira adequada. 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 é 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 atuais.

EventUpdated

(instalável)
authMode

Um valor do tipo enumerado ScriptApp.AuthMode.

FULL
calendarId

O ID da string da agenda em que a atualização do evento ocorreu.

susan@example.com
triggerUid

ID do acionador que produziu esse 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 os objetos de evento no Google Chat, consulte Receber e responder a interações com o app do Google Chat.

Eventos baseados no 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 o nome dessa propriedade contém traços, ele precisa ser acessado por e['day-of-month'] em vez de notação de ponto.

31
day-of-week

Entre 1 (segunda-feira) e 7 (domingo).

Como o nome dessa propriedade contém traços, ele precisa ser acessado por e['day-of-week'] em vez de 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 acionador que produziu esse evento.

4034124084959907503
week-of-year

Entre 1 e 52.

Como o nome dessa propriedade contém traços, ele precisa ser acessado por e['week-of-year'] em vez de notação de ponto.

52
year

O ano.

2015