Agendas e eventos

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

Agendas

Uma agenda é uma coleção de eventos relacionados, além de 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 ser compartilhadas com outras pessoas. As agendas principais pertencem à conta de usuário associada. As outras agendas pertencem a um único proprietário de dados.

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, local, status, lembretes, anexos etc.

Tipos de evento

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

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

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

• Um evento programado ocorre entre dois pontos específicos no tempo. Os eventos programados 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.

O início e o fim do evento precisam ser programados ou de dia inteiro. Por exemplo, não é válido especificar start.date e end.dateTime.

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 convidados. 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 associada a uma única conta de usuário. Essa agenda é criada automaticamente para cada novo usuário e o ID dela 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 "desvinculada" do usuário. No entanto, ela ainda pode ser compartilhada com outros usuários.

Além da agenda principal, você pode criar explicitamente qualquer número de outras agendas. Essas agendas podem ser modificadas, excluídas e compartilhadas com outras pessoas. Essas agendas têm um único proprietário de dados com os privilégios mais altos, incluindo o direito exclusivo de excluir a agenda. O nível de acesso do proprietário de dados não pode ser reduzido. O proprietário de dados é determinado inicialmente como o usuário que criou a agenda. No entanto, a propriedade dos dados pode ser transferida na interface do Google Agenda.

Importante:ao criar uma agenda, recomendamos que seu app faça a autenticação como o proprietário de dados pretendido da agenda. Você pode usar a delegação de autoridade em todo o domínio para permitir que os aplicativos atuem em nome de um usuário específico. Não use uma conta de serviço para autenticação. Se você usar uma conta de serviço para autenticação, ela será o proprietário dos dados, o que pode levar a um comportamento inesperado. Por exemplo, se uma conta de serviço for o proprietário dos dados, a propriedade dos dados não poderá ser transferida.

Agenda e lista de agendas

A coleção Calendars representa todas as agendas existentes. Ela pode ser usada 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 de agenda que um usuário adicionou à lista (mostrada no painel esquerdo da interface da Web). É possível usá-la para adicionar e remover agendas da lista de usuários. Ela também é usada para recuperar e definir os valores de propriedades de agenda específicas do usuário, como lembretes padrão. Outro exemplo é a cor de primeiro plano, já que usuários diferentes podem ter cores diferentes definidas para a mesma agenda.

Observação: o proprietário de dados de uma agenda não pode remover essa agenda da lista.

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

Operação	Agendas	CalendarList
insert	Cria uma nova agenda secundária. Essa agenda também é adicionada à lista de agendas do criador e não pode ser removida, a menos que a agenda seja excluída ou transferida.	Insere uma agenda 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, 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 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 terem horários de início e término diferentes, esses eventos repetidos costumam ser idênticos.

Os eventos são chamados de recorrentes se forem repetidos de acordo com uma programação definida. Os 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 independente) 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 RRULE, RDATE ou EXDATE propriedades, conforme definido em RFC 5545.

A propriedade RRULE é a mais importante, porque define uma regra regular para repetir o evento. Ela é composta por vários componentes. Alguns deles são:

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

• INTERVAL : funciona com FREQ para especificar a frequência com que o evento deve 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.

  Você pode usar COUNT ou UNTIL para especificar o fim da recorrência do evento. Não use os dois na mesma regra.

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

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

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

A propriedade EXDATE é semelhante a RDATE, mas especifica datas ou horários 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 horários) 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.

Confira alguns exemplos de eventos recorrentes:

1. Um evento que acontece das 6h às 7h todas as terças e sextas-feiras, começando em 15 de setembro de 2015 e parando 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 1º de junho de 2015 e se repete a cada três dias durante todo o 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: as ocorrências específicas em momentos diferentes. Essas instâncias atuam como eventos.

As modificações de eventos recorrentes podem afetar o evento recorrente inteiro (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 diferente, um horário de início diferente ou convidados adicionais 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 status do evento).

Confira exemplos de como trabalhar com eventos e instâncias recorrentes usando a API Google Agenda. Eles podem ser encontrados aqui.

Fusos horários

Um fuso horário especifica uma região que observa um horário padrão uniforme. Na API Google Agenda, você especifica fusos horários usando identificadores de fuso horário da 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 da agenda também é conhecido como fuso horário padrão devido às implicações para os resultados da consulta. O fuso horário da agenda afeta a maneira como os valores de tempo são interpretados ou apresentados pelos events.get(), events.list() e events.instances() métodos.

Conversão de fuso horário do resultado da consulta

Os resultados dos get(), list() e instances() métodos são retornados no fuso horário especificado no timeZone parâmetro. Se você omitir esse parâmetro, todos esses métodos usarão o fuso horário da agenda como padrão.

Como corresponder eventos de dia inteiro a consultas com intervalo de tempo

Os list() e instances() métodos permitem especificar filtros de horário de início e término, com o método retornando instâncias que estão no intervalo especificado. O fuso horário da agenda é usado para calcular os horários de início e término de eventos de dia inteiro para determinar se eles estão dentro da especificação do filtro.

Fuso horário do evento

As instâncias de eventos 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 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 deslocamento, 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 deslocamento, por exemplo, 2017-01-25T09:00:00, mas use o campo timeZone 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 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, assim como quando você define um fuso horário de evento usando a interface do Agenda UI:

Para eventos únicos, é possível especificar fusos horários diferentes para os horários de início e término de um evento. Isso pode ajudar com eventos, como viagens, que realmente começam e terminam em fusos horários diferentes. Para eventos recorrentes, consulte abaixo.

Fuso horário de eventos recorrentes

Para eventos recorrentes, um único fuso horário precisa ser especificado. Ele é necessário para expandir as recorrências do evento.