Esta página foi traduzida pela API Cloud Translation.

Tipos de evento

Nesta página, explicamos a propriedade eventType e as especificações dos tipos de eventos disponíveis na API Google Agenda.

O Google Agenda permite que os usuários criem eventos genéricos, bem como eventos projetados para casos de uso específicos e com propriedades personalizadas.

O tipo de evento pode ser descoberto nos seguintes locais da API:

Todos os eventos são retornados com um eventType.
O eventType precisa ser definido ao criar ou atualizar um recurso de evento. Se não for definido, o tipo 'default' será usado.
eventTypes pode ser especificado em uma chamada Events:list para listar eventos de tipos específicos. Se nenhum tipo for especificado, todos os tipos de evento serão retornados.
eventTypes pode ser especificado em uma chamada Events:watch para se inscrever em atualizações sobre eventos de tipos específicos. Se nenhum tipo for especificado, a solicitação vai resultar na inscrição em todos os tipos de eventos.

Evento padrão

Os eventos do tipo default são criados e usados como um dos principais recursos da API Google Calendar. Elas oferecem suporte a uma ampla variedade de propriedades que podem ser usadas para personalizar ainda mais o evento.

Consulte Criar eventos para começar a trabalhar com eventos do Google Agenda.

Aniversário

Os aniversários são eventos especiais de dia inteiro com recorrência anual.

Os usuários podem criar eventos de aniversário manualmente no Google Agenda. Além disso, as informações de aniversário são sincronizadas com o Google Agenda quando os usuários adicionam uma pessoa e incluem o aniversário dela e outras datas importantes nos Contatos do Google. O aniversário dos usuários também é sincronizado com o Google Agenda no perfil da Conta do Google.

A API Google Calendar oferece suporte aos métodos get, instances e list para leitura de eventos de aniversário. eventTypes pode ser definido como 'birthday' para listar apenas eventos de aniversário. Se nenhum tipo for especificado, os aniversários serão listados com todos os outros tipos de eventos.

Nos objetos Event retornados, inspecione o campo birthdayProperties para mais detalhes sobre esse evento especial. birthdayProperties tem os seguintes campos:

type: tipo de evento especial, seja um aniversário, uma data comemorativa ou outra data importante.
customTypeName: rótulo especificado pelo usuário para esse evento especial. Esse campo será preenchido se type estiver definido como 'custom'.
contact: Nome do recurso do contato a que este evento especial está vinculado, se houver. Ele tem o formato 'people/c12345' e pode ser usado para buscar detalhes de contato na API People.

A API permite criar eventos de aniversário usando o método insert com as seguintes especificações:

eventType, definida como 'birthday'.
Os campos start e end precisam definir um evento de dia inteiro que dure exatamente um dia.
O valor do campo visibility precisa ser 'private'.
O valor do campo transparency precisa ser 'transparent'.
Precisa ter uma recorrência anual, o que significa que o campo recurrence precisa ser 'RRULE:FREQ=YEARLY'. Os eventos de aniversário que caem em 29 de fevereiro precisam ter a seguinte regra de recorrência: 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'.
Pode ter um colorId, summary e reminders.
Pode ter birthdayProperties. Se especificado, type precisa ser 'birthday', e customTypeName e contact precisam estar vazios.
Não pode ter outras propriedades de evento.

A API permite atualizar os campos colorId, summary e reminders de eventos de aniversário usando os métodos update e patch. Os campos start e end também podem ser atualizados para mudar a data do evento. Nesse caso, os novos valores precisam definir um evento de dia inteiro que dure exatamente um dia. Não é possível atualizar os detalhes de horário de um evento de aniversário se ele estiver vinculado a um contact ou se o type dele for 'self'.

A API Google Calendar não permite criar eventos de aniversário com birthdayProperties personalizados nem atualizar essas propriedades. As datas importantes podem ser editadas com a API People, e as mudanças são sincronizadas com o Google Agenda. Da mesma forma, os usuários podem editar a própria data de nascimento no perfil da Conta do Google, e ela é sincronizada com a Agenda.

As solicitações que tentarem criar ou atualizar um aniversário de uma forma não compatível vão falhar. Nesse caso, inspecione a mensagem de erro para identificar o problema.

A API oferece suporte à operação import para eventos de aniversário, mas o evento será importado como um evento padrão. Em outras palavras, o eventType será 'default'.

A API é compatível com o método watch para se inscrever em mudanças nos eventos de aniversário do Google Agenda. eventTypes pode ser definido como 'birthday' para se inscrever em atualizações sobre eventos de aniversário. Se nenhum tipo for especificado, todos os tipos de eventos, incluindo aniversários, serão inscritos.

Os eventos de aniversário podem ser excluídos usando o método delete da API Google Calendar. Excluir um evento de aniversário do Google Agenda não afeta os dados nos Contatos do Google ou no perfil da Conta do Google.

Não é possível mudar o organizador de um evento de aniversário usando os métodos move ou update.

Eventos do Gmail

Os eventos gerados automaticamente no Gmail têm o tipo 'fromGmail'.

A API Google Calendar não permite criar esse tipo de evento usando o método insert.

A API permite atualizar as propriedades estendidas colorId, reminders, visibility, transparency, status, attendees, private e shared usando os métodos update e patch.

A API é compatível com os métodos get e list para ler eventos do Gmail. eventTypes pode ser definido como 'fromGmail' para listar apenas eventos gerados no Gmail. Se nenhum tipo for especificado, os eventos do Gmail serão listados com todos os outros tipos de eventos.

A API é compatível com o método watch para se inscrever em mudanças nos eventos do Gmail no Google Agenda. Se nenhum tipo for especificado, todos os tipos de eventos, incluindo 'fromGmail', serão inscritos.

Os eventos do Gmail podem ser excluídos usando o método delete da API Google Calendar.

Não é possível mudar o organizador de um evento no Gmail usando os métodos move ou update.

Horário de concentração, fora do escritório e local de trabalho

A API Google Calendar pode ser usada para criar e gerenciar eventos que mostram o status dos usuários do Google Agenda.

Esses recursos estão disponíveis apenas nas agendas principais e para alguns usuários do Google Agenda. Consulte Gerenciar eventos de horário de concentração, fora do escritório e local de trabalho para saber mais.

Conheça os tipos de eventos no Google Apps Script

O Google Apps Script é uma linguagem de script baseada em JavaScript que permite criar aplicativos empresariais integrados ao Google Workspace. Os scripts são desenvolvidos em um editor de código baseado em navegador e armazenados e executados nos servidores do Google. Consulte também o início rápido do Google Apps Script para começar a usar o Apps Script e enviar solicitações à API Google Agenda.

As instruções a seguir descrevem como ler e gerenciar eventos usando a API Google Calendar como um serviço avançado no Google Apps Script. Para uma lista completa de recursos e métodos da API Google Agenda, consulte a documentação de referência.

Criar e configurar o script

Acesse script.google.com/create para criar um script.
No painel à esquerda, ao lado de Serviços, clique em Adicionar um serviço .
Selecione API Google Calendar e clique em Adicionar.
Depois de ativada, a API aparece no painel à esquerda. Os métodos e classes disponíveis na API podem ser listados usando a palavra-chave Calendar no editor.

(Opcional) Atualizar o projeto do Google Cloud

Cada projeto do Google Apps Script tem um projeto do Google Cloud associado. O script pode usar o projeto padrão que o Google Apps Script cria automaticamente. Se você quiser usar um projeto personalizado do Google Cloud, consulte Mudar para um projeto padrão diferente do Cloud. Depois de definir o projeto do Google Cloud, selecione Editor no lado esquerdo para voltar ao editor de código.

Adicionar código ao script

A amostra de código a seguir mostra como listar, ler e criar eventos com diferentes valores de eventType.

Cole o seguinte no editor de código.

const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => console.log(event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
  */
function readEvent() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

Substitua:

CALENDAR_ID: endereço de e-mail da agenda para recuperar e criar eventos. Inicialmente, essa constante é definida como 'primary', que é uma palavra-chave para acessar a agenda principal do usuário conectado. Ao mudar esse valor, você pode ler eventos nas agendas de outros usuários a que tem acesso.
EVENT_ID: ID do evento. Chame Events:list para recuperar IDs de eventos.

Executar a amostra de código

Acima do editor de código, selecione a função a ser executada no menu suspenso e clique em Executar.
Na primeira execução, ele pede que você autorize o acesso. Revise e permita que o Apps Script acesse sua agenda.
É possível inspecionar os resultados da execução do script no Registro de execução que aparece na parte de baixo da janela.