Este guia descreve agendas, 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 período específico. Os eventos são identificados por um ID exclusivo. Além de uma data e hora de início e término, os eventos contêm outros dados, como resumo, descrição, localização, status, lembretes, anexos etc.
Tipos de evento
O Google Agenda é compatível com 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 timed ocorre entre dois pontos específicos no tempo. Os eventos cronometrados usam os campos
start.dateTime
eend.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
eend.date
para especificar quando ocorrem. O campo de fuso horário não é relevante para eventos de dia inteiro.
Organizadores
Os eventos têm um único organizador, que é a agenda que contém a cópia principal do evento. Os eventos também podem ter vários participantes. Um convidado geralmente é 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 associado 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 "pertencente" ao usuário. No entanto, ela ainda poderá ser compartilhada com outros usuários.
Além da agenda principal, é possível criar explicitamente quantas outras agendas você quiser, que podem ser modificadas, excluídas e compartilhadas entre vários usuários.
Agenda e lista de agendas
A coleção Calendars 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 é um conjunto de todas as entradas de agenda que um usuário adicionou à lista (mostrado no painel esquerdo da IU da Web). É possível usá-lo para adicionar e remover agendas da lista de usuários. Também é possível usá-lo para recuperar e definir os valores de propriedades de agenda específicas do usuário, como lembretes padrão. Outro exemplo é a cor do primeiro plano, já que usuários diferentes podem ter diferentes cores definidas para a mesma agenda.
A tabela a seguir compara o significado das operações das 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 na lista do usuário. |
delete |
Exclui uma agenda secundária. | Remove uma agenda da lista do usuário. |
get |
Recupera os metadados da agenda, como título e fuso horário. | Recupera metadados, além de personalização específica do usuário, como cores ou lembretes de substituição. |
patch /update |
Modifica os metadados da agenda. | Modifica as 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.
Os 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 término (que definem a primeira ocorrência, como se fosse apenas um evento único); e
O campo de recorrência (que define como o evento deve 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 na RFC 5545 (em inglês).
A propriedade RRULE
é a mais importante, porque define uma regra regular para repetir o evento. Ele é composto por vários componentes. Alguns deles são:
FREQ
: a frequência com que o evento deve ser repetido (comoDAILY
ouWEEKLY
). Obrigatório.INTERVAL
: funciona comFREQ
para especificar com que frequência o evento precisa ser repetido. Por exemplo,FREQ=DAILY;INTERVAL=2
significa uma vez a cada dois dias.COUNT
: número de vezes que esse evento deve ser repetido.UNTIL
: a data ou data-hora em que o evento deve se repetir (inclusive).BYDAY
: dias da semana em que o evento deve ser repetido (SU
,MO
,TU
etc.). Outros componentes semelhantes incluemBYMONTH
,BYYEARDAY
eBYHOUR
.
A propriedade RDATE
especifica outras datas ou datas/horas em que as ocorrências do evento devem acontecer. Por exemplo, RDATE;VALUE=DATE:19970101,19970120
.
Use esse método para adicionar outras ocorrências não cobertas pela RRULE
.
A propriedade EXDATE
é semelhante à RDATE, mas especifica as datas ou datas-hora
em que o evento não deve 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 data-hora) para eventos de dia inteiro.
Cada uma dessas 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:
Um evento que acontecerá das 6h às 7h, todas as terças e sextas-feiras, começando em 15 de setembro de 2015 e terminando 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" ], …
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 atuam como eventos.
As modificações recorrentes podem afetar todo o evento recorrente (e todas as instâncias dele) ou apenas instâncias individuais. Instâncias que diferem do evento recorrente pai são chamadas de exceções.
Por exemplo, uma exceção pode ter um resumo diferente, um horário de início diferente ou outros convidados convidados apenas para essa instância. Também é possível cancelar uma
instância sem remover o evento recorrente.
Os cancelamentos da instância são refletidos no evento
status
.
Confira aqui exemplos de como trabalhar com eventos e instâncias recorrentes com a 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, use identificadores de fuso horário IANA para especificar fusos horários.
Você pode definir o fuso horário de agendas e eventos. As seções a seguir descrevem os efeitos dessas configurações.
Fuso horário da agenda
O fuso horário da agenda também é conhecido como fuso horário padrão por causa das implicações nos resultados da consulta. O fuso horário da agenda afeta a maneira 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()
einstances()
são retornados no fuso horário especificado no parâmetrotimeZone
. Se você omitir esse parâmetro, todos esses métodos usarão o fuso horário da agenda como padrão. - Correspondência de eventos de dia inteiro com consultas com intervalo de tempo
- Os métodos
list()
einstances()
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 da agenda é usado para calcular os horários de início e término dos 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 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 seguintes especificam o mesmo horário:
- Inclua uma diferença de fuso horário no campo
dateTime
, por exemplo,2017-01-25T09:00:00-0500
. - Especifique o horário sem deslocamento, por exemplo,
2017-01-25T09:00:00
, deixando o campotimeZone
vazio (isso usa implicitamente o fuso horário padrão). - Especifique o horário sem deslocamento, por exemplo,
2017-01-25T09:00:00
, mas use o campotimeZone
para especificar o fuso horário.
Também é possível especificar horários de eventos em UTC, se preferir:
- Especifique o horário em UTC:
2017-01-25T14:00:00Z
ou use um deslocamento zero em2017-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, assim como você define um fuso horário do evento usando a interface do Google Agenda:
Fuso horário de evento recorrente
Para eventos recorrentes, é preciso sempre especificar um único fuso horário. Ela é necessária para expandir as recorrências do evento.