Agendas e eventos

Este guia descreve as agendas, os eventos e a relação entre eles.

Calendários

Uma agenda é uma coleção de eventos relacionados, com outros metadados, como resumo, fuso horário padrão, local etc. Cada agenda é identificada por um ID, que é um endereço de e-mail. As agendas podem ter vários proprietários.

Eventos

Um evento é um objeto associado a uma data ou um período específico. Os eventos são identificados por um ID exclusivo. Além de uma data-hora de início e término, os eventos contêm outros dados, como resumo, descrição, local, status, lembretes, anexos etc.

Tipos de evento

O Google Agenda oferece suporte a eventos únicos e recorrentes:

  • Um único evento representa uma ocorrência única.
  • Um evento recorrente define várias ocorrências.

Os eventos também podem ser cronometrados ou de dia inteiro:

  • Um evento cronometrado ocorre entre dois momentos específicos. Os eventos cronometrados usam os campos start.dateTime e end.dateTime para especificar quando ocorrem.
  • Um evento de dia inteiro abrange um dia inteiro ou uma série de dias consecutivos. Os eventos de dia inteiro usam os campos start.date e end.date para especificar quando ocorrem. O campo de fuso horário não tem significado para eventos de dia inteiro.

Organizadores

Os eventos têm um único organizador, que é a agenda com a cópia principal do evento. Os eventos também podem ter vários participantes. Em geral, um convidado é a agenda principal de um usuário convidado.

O diagrama a seguir mostra a relação conceitual entre agendas, eventos e outros elementos relacionados:

Agendas principais e outras agendas

Uma agenda principal é um tipo especial de agenda associada a uma única conta de usuário. Essa agenda é criada automaticamente para cada nova conta de usuário, e o ID geralmente corresponde ao endereço de e-mail principal do usuário. Enquanto a conta existir, a agenda principal dela nunca poderá ser excluída ou não ser de propriedade do usuário. No entanto, ele ainda poderá ser compartilhado com outros usuários.

Além da agenda principal, é possível criar explicitamente quantas outras agendas você quiser. Elas podem ser modificadas, excluídas e compartilhadas entre vários usuários.

Agenda e lista de agendas

A coleção Agendas representa todas as agendas existentes. Ele pode ser usado para criar e excluir agendas. Também é possível recuperar ou definir propriedades globais compartilhadas entre todos os usuários com acesso a uma agenda. Por exemplo, o título e o fuso horário padrão de uma agenda são propriedades globais.

A CalendarList é uma coleção de todas as entradas da agenda que um usuário adicionou à lista (mostrada no painel esquerdo da IU da Web). Você pode usá-lo para adicionar e remover agendas da lista dos usuários. Use-o também para recuperar e definir os valores de propriedades específicas da agenda do usuário, como lembretes padrão. Outro exemplo é a cor do primeiro plano, já que usuários diferentes podem ter cores diferentes definidas para a mesma agenda.

A tabela a seguir compara o significado das operações para as duas coleções:

Operação Calendários CalendarList
insert Cria uma nova agenda secundária. Por padrão, essa agenda também é adicionada à lista de agendas do criador. Insere uma agenda existente na lista do usuário.
delete Exclui uma agenda secundária. Remove uma agenda da lista do usuário.
get Recupera metadados da agenda, por exemplo, título ou fuso horário. Recupera metadados e personalização específica do usuário, como cor ou lembretes de substituição.
patch/update Modifica os metadados da agenda. Modifica propriedades da agenda específicas do usuário.

Eventos recorrentes

Alguns eventos ocorrem várias vezes em uma programação regular, como reuniões semanais, aniversários e feriados. Além de ter horários de início e término diferentes, esses eventos repetidos costumam ser idênticos.

Eventos são chamados de recorrentes quando se repetem de acordo com uma programação definida. Eventos únicos não são recorrentes e acontecem apenas uma vez.

Regra de recorrência

A programação de um evento recorrente é definida em duas partes:

  • os campos de início e fim, que definem a primeira ocorrência, como se fosse um único evento independente;

  • O campo de recorrência, que define como o evento será repetido ao longo do tempo.

O campo de recorrência contém uma matriz de strings que representam uma ou várias propriedades RRULE, RDATE ou EXDATE, conforme definido no RFC 5545.

A propriedade RRULE é a mais importante, porque define uma regra regular para repetir o evento. Ele tem vários componentes. Algumas delas são:

  • FREQ: a frequência com que o evento precisa ser repetido (como DAILY ou WEEKLY). Obrigatório.

  • INTERVAL: funciona com FREQ para especificar a frequência de repetição do evento. Por exemplo, FREQ=DAILY;INTERVAL=2 significa uma vez a cada dois dias.

  • COUNT: número de vezes que o evento será repetido.

  • UNTIL: a data ou data-hora até a qual o evento será repetido (inclusive).

  • BYDAY: dias da semana em que o evento será repetido (SU, MO, TU etc.). Outros componentes semelhantes incluem BYMONTH, BYYEARDAY e BYHOUR.

A propriedade RDATE especifica outras datas ou datas-horas em que as ocorrências do evento precisam acontecer. Por exemplo, RDATE;VALUE=DATE:19970101,19970120. Use para adicionar outras ocorrências não cobertas pela RRULE.

A propriedade EXDATE é semelhante à RDATE, mas especifica datas ou datas-horas em que o evento não pode acontecer. Ou seja, essas ocorrências precisam ser excluídas. Isso precisa apontar para uma instância válida gerada pela regra de recorrência.

EXDATE e RDATE podem ter um fuso horário e precisam ser datas (não datas-horas) para eventos de dia inteiro.

Cada uma das propriedades pode ocorrer várias vezes no campo de recorrência. A recorrência é definida como a união de todas as regras RRULE e RDATE, menos as excluídas por todas as regras EXDATE.

Veja alguns exemplos de eventos recorrentes:

  1. Um evento que acontece das 6h às 7h todas as terças e sextas-feiras a partir de 15 de setembro de 2015 e termina após a quinta ocorrência em 29 de setembro:

    ...
    "start": {
     "dateTime": "2015-09-15T06:00:00+02:00",
     "timeZone": "Europe/Zurich"
    },
    "end": {
     "dateTime": "2015-09-15T07:00:00+02:00",
     "timeZone": "Europe/Zurich"
    },
    "recurrence": [
     "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR"
    ],
    …
    
  2. Um evento de dia inteiro que começa em 1o de junho de 2015 e se repete a cada três dias ao longo do mês, excluindo 10 de junho, mas incluindo 9 e 11 de junho:

    ...
    "start": {
     "date": "2015-06-01"
    },
    "end": {
     "date": "2015-06-02"
    },
    "recurrence": [
     "EXDATE;VALUE=DATE:20150610",
     "RDATE;VALUE=DATE:20150609,20150611",
     "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3"
    ],
    …
    

Instâncias e exceções

Um evento recorrente consiste em várias instâncias: ocorrências específicas em momentos diferentes. Essas instâncias agem como eventos.

As modificações de eventos recorrentes podem afetar todo o evento recorrente (e todas as instâncias dele) ou apenas instâncias individuais. As instâncias que diferem do evento recorrente pai são chamadas de exceções.

Por exemplo, uma exceção pode ter um resumo ou horário de início diferente ou outros participantes convidados apenas para essa instância. Também é possível cancelar uma instância sem remover o evento recorrente. Os cancelamentos de instâncias são refletidos no evento status.

Veja aqui exemplos de como trabalhar com eventos e instâncias recorrentes por meio da API Google Calendar.

Fusos horários

Um fuso horário especifica uma região que observa um horário padrão uniforme. Na API Google Calendar, especifique os fusos horários usando identificadores de fuso horário IANA.

É possível definir o fuso horário para agendas e eventos. As seções a seguir descrevem os efeitos dessas configurações.

Fuso horário da agenda

O fuso horário do calendário também é conhecido como fuso horário padrão devido às implicações nos resultados da consulta. O fuso horário da agenda afeta a forma como os valores de tempo são interpretados ou apresentados pelos métodos events.get(), events.list() e events.instances().

Conversão de fuso horário do resultado da consulta
Os resultados dos métodos get(), list() e instances() são retornados no fuso horário especificado no parâmetro timeZone. Se você omitir esse parâmetro, todos esses métodos usarão o fuso horário do calendário como padrão.
Correspondência de eventos de dia inteiro a consultas com colchetes
Os métodos list() e instances() permitem especificar filtros de horário de início e término, com o método retornando instâncias que se enquadram no intervalo especificado. O fuso horário do calendário é usado para calcular os horários de início e término de eventos de dia inteiro e determinar se eles se enquadram na especificação do filtro.

Fuso horário do evento

As instâncias de evento têm um horário de início e de término. A especificação desses horários pode incluir o fuso horário. É possível especificar o fuso horário de várias maneiras. Todas as opções a seguir especificam o mesmo horário:

  • Inclua um deslocamento de fuso horário no campo dateTime, por exemplo, 2017-01-25T09:00:00-0500.
  • Especifique o horário sem ajuste, por exemplo, 2017-01-25T09:00:00, deixando o campo timeZone vazio (isso usa implicitamente o fuso horário padrão).
  • Especifique o horário sem ajuste, por exemplo, 2017-01-25T09:00:00, mas use o campo timeZone para especificar o fuso horário.

Você também pode especificar os horários do evento em UTC, se preferir:

  • Especifique o horário em UTC: 2017-01-25T14:00:00Z ou use um deslocamento de zero para 2017-01-25T14:00:00+0000.

A representação interna do horário do evento é a mesma em todos esses casos, mas definir o campo timeZone anexa um fuso horário ao evento, da mesma forma que quando você define um fuso horário de evento usando a interface do Agenda:

Fragmento da captura de tela mostrando o fuso horário de um evento

Fuso horário de evento recorrente

Para eventos recorrentes, é preciso sempre especificar um único fuso horário. Ele é necessário para expandir as recorrências do evento.