Agendas e eventos

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

Agendas

Uma agenda é uma coleção de eventos relacionados, junto com metadados adicionais 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 intervalo de tempo específico. Os eventos são identificados por um ID exclusivo. Além de um início data/hora de 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. Eventos com marcação de tempo use os campos start.dateTime e end.dateTime para especificar quando antes que ocorram mudanças.
  • Um evento de dia inteiro abrange um dia inteiro ou uma série de dias consecutivos. Dia todo Os eventos usam os campos start.date e end.date para especificar quando eles 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árias participantes. Um convidado geralmente é a agenda principal de um usuário convidado.

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

Agendas principais e outras agendas

Uma agenda principal é um tipo especial de agenda associada a uma única agenda conta de usuário. Esta agenda é criada automaticamente para cada nova conta de usuário e seu ID geralmente corresponde ao endereço de e-mail principal do usuário. Enquanto o conta existir, a agenda principal dela nunca poderá ser excluída ou "não pertence" ao usuário. No entanto, ela ainda poderá 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 entre vários usuários.

Agenda e lista de agendas

A coleção Calendars representa todas as agendas existentes. Ela pode ser usada para criar e excluir agendas. Você também pode recuperar ou definir propriedades globais compartilhadas em todos usuários com acesso a uma agenda. Por exemplo, o título e padrão de uma agenda fuso horário são propriedades globais.

A CalendarList é uma de todos os itens da agenda que um usuário adicionou à lista (mostrado no painel esquerdo da IU da Web). É possível usá-lo para adicionar e remover agendas de/para a lista de usuários. Ele também pode ser usado para recuperar e definir valores de propriedades da agenda específicas do usuário, como lembretes padrão. Outra exemplo é a cor de primeiro plano, já que usuários diferentes podem ter cores diferentes definido para a mesma agenda.

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

Operação Agendas CalendarList
insert Cria uma nova agenda secundária. Por padrão, esta agenda também é adicionado à 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 metadados de calendário, por exemplo, título, 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:

  • Seus campos de início e término (que definem a primeira ocorrência, como se ela fosse um único evento individual), 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 no RFC. 5545.

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 (como DAILY ou WEEKLY). Obrigatório.

  • INTERVAL: trabalha com FREQ para especificar a frequência do evento. deve ser repetido. Por exemplo, FREQ=DAILY;INTERVAL=2 significa que 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 incluem BYMONTH, BYYEARDAY e BYHOUR

A propriedade RDATE especifica outras datas ou datas-hora em que o evento ocorrerão. 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 a RDATE, mas especifica datas ou datas-horas. quando o evento não deve acontecer. Ou seja, essas ocorrências devem ser excluídos. 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 de RRULE e RDATE, menos a excluídos 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 que começa a partir de 15 de setembro de 2015 e com término 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 atuam como eventos.

Modificações recorrentes em eventos podem afetar evento recorrente (e todas as suas instâncias) 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 ou um horário de início diferentes, ou convidados adicionais apenas para essa instância. Você também pode cancelar completamente sem remover o evento recorrente Os cancelamentos de instâncias são refletidos no evento status).

Exemplos de como trabalhar com eventos e instâncias recorrentes pelo Você encontra a API Google Calendar aqui.

Fusos horários

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

Você pode definir o fuso horário de agendas e eventos. As seções a seguir e descrever os efeitos dessas configurações.

Fuso horário da agenda

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

Conversão de fuso horário do resultado da consulta
Os resultados get(), list() e instances() forem retornados no fuso horário especificado em timeZone . Se você omitir esse parâmetro, todos esses métodos usarão a classe como padrão.
Correspondência de eventos de dia inteiro com consultas com intervalo de tempo
O list() e instances() permitem especificar filtros de horário de início e término, com o método instâncias recorrentes 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 para determinar se eles se enquadram na especificação de 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. 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 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 em 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 um evento usando a Agenda Interface:

Fragmento de 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. Ela é necessária para expandir as recorrências do evento.