Objetos de evento

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

Com os acionadores simples e os acionadores instaláveis, o Apps Script pode executar uma função automaticamente caso ocorra um determinado evento. Quando um acionador é disparado, o Apps Script transmite a 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 disparo do acionador. Por exemplo, o exemplo de código abaixo mostra um acionador onEdit(e) simples para um script do 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());
}

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

Eventos do 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.

Aberto

(simples e instalável)
authMode

Um valor da enumeração ScriptApp.AuthMode.

LIMITED
source

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

Spreadsheet
triggerUid

Código do acionador que produziu o evento (somente acionadores 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

Mudar

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

Código do acionador que produziu o 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 instalável)
authMode

Um valor da enumeração ScriptApp.AuthMode.

LIMITED
oldValue

Valor da célula anterior à 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 editadas.

Range
source

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

Spreadsheet
triggerUid

Código do acionador que produziu o evento (somente acionadores 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 valores da pergunta 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 editadas.

Range
triggerUid

Código do acionador que produziu o 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

Com os acionadores, o Documentos Google pode responder quando um usuário abre um arquivo.

Aberto

(simples e instalável)
authMode

Um valor da enumeração ScriptApp.AuthMode.

LIMITED
source

Um objeto Document, que representa o arquivo do Documentos Google a que o script está vinculado.

Document
triggerUid

Código do acionador que produziu o evento (somente acionadores 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

Com os acionadores, o Apresentações Google pode responder quando um usuário abre um arquivo.

Aberto

(simples)
authMode

Um valor da enumeração ScriptApp.AuthMode.

LIMITED
source

Um objeto Presentation, que representa o arquivo do Apresentações Google 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 do Formulários Google

Os acionadores específicos dos Formulários Google permitem que os scripts respondam quando um usuário edite um formulário ou envie uma resposta.

Aberto

* (simples e instalável)
authMode

Um valor da enumeração ScriptApp.AuthMode.

LIMITED
source

Um objeto Form, que representa o arquivo do Formulários Google ao qual o script está vinculado.

Form
triggerUid

Código do acionador que produziu o evento (somente acionadores 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 Formulários Google ao qual o script está vinculado.

Form
triggerUid

Código do acionador que produziu o evento.

4034124084959907503

Eventos do Google Agenda

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

Eles não informam qual evento mudou ou como isso mudou. Em vez disso, elas indicam que o código precisa executar uma operação de sincronização incremental para selecionar alterações recentes na agenda. Para ver uma descrição completa deste 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 Agenda para o projeto de script. O serviço do Agenda integrado não é suficiente para este fluxo de trabalho.
  2. Determine quais agendas devem ser sincronizadas. Para cada uma dessas agendas, execute 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 indicar um disparo de alteração do evento da agenda, execute uma sincronização incremental para a agenda afetada usando o nextSyncToken armazenado. Basicamente, é outra solicitação Events.list(). No entanto, fornecer nextSyncToken limita a resposta a apenas eventos que foram alterados desde a última sincronização.
  5. Examine a resposta da sincronização para saber quais eventos foram atualizados e fazer com que seu código responda adequadamente. Por exemplo, você pode registrar a alteração, atualizar uma planilha, enviar avisos por e-mail ou realizar outras ações.
  6. Atualize o nextSyncToken armazenado nessa agenda com o retornado pela solicitação de sincronização incremental. Isso força a próxima operação de sincronização a retornar apenas as alterações mais atuais.

Evento atualizado

(instalável)
authMode

Um valor da enumeração ScriptApp.AuthMode.

FULL
calendarId

O código da string da agenda em que ocorreu a atualização de evento.

susan@example.com
triggerUid

Código do acionador que produziu o evento.

4034124084959907503

Eventos dos complementos

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

Instalar

(simples)
authMode

Um valor da enumeração ScriptApp.AuthMode.

FULL

Eventos baseados em tempo

Os acionadores baseados em tempo, também chamados de acionadores de relógio, permitem que os scripts sejam executados em um momento 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 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 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

Código do acionador que produziu o 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 de ponto.

52
year

O ano.

2015