Calendarios y eventos

En esta guía, se describen los calendarios, los eventos y su relación entre sí.

Calendarios

Un calendario es una colección de eventos relacionados, junto con metadatos adicionales, como resumen, zona horaria predeterminada, ubicación, etc. Cada calendario se identifica con un ID que es una dirección de correo electrónico. Los calendarios pueden tener varios propietarios.

Eventos

Un evento es un objeto asociado con una fecha o un intervalo de tiempo específicos. Los eventos se identifican con un ID único. Además de una fecha y hora de inicio y finalización, los eventos contienen otros datos, como resumen, descripción, ubicación, estado, recordatorios, archivos adjuntos, etcétera.

Tipos de eventos

El Calendario de Google admite eventos únicos y recurrentes:

  • Un solo evento representa un caso único.
  • Un evento recurrente define varios casos.

Los eventos también pueden tener un cronograma o un evento de todo el día:

  • Un evento temporizado ocurre entre dos momentos específicos. Los eventos temporizados usan los campos start.dateTime y end.dateTime para especificar cuándo ocurren.
  • Un evento de todo el día abarca un día completo o una serie de días consecutivos. Los eventos de todo el día usan los campos start.date y end.date para especificar cuándo ocurren. Ten en cuenta que el campo de zona horaria no tiene importancia para los eventos que duran todo el día.

Organizadores

Los eventos tienen un solo organizador, que es el calendario que contiene la copia principal del evento. Los eventos también pueden tener varios asistentes. Un asistente suele ser el calendario principal de un usuario invitado.

En el siguiente diagrama, se muestra la relación conceptual entre calendarios, eventos y otros elementos relacionados:

Calendarios principales y otros calendarios

Un calendario principal es un tipo especial de calendario asociado con una sola cuenta de usuario. Este calendario se crea automáticamente para cada cuenta de usuario nueva y su ID suele coincidir con la dirección de correo electrónico principal del usuario. Mientras la cuenta exista, el usuario nunca podrá borrar su calendario principal ni dejarlo de ser propietario. Sin embargo, podrás seguir compartiéndolo con otros usuarios.

Además del calendario principal, puedes crear de forma explícita cualquier cantidad de calendarios que se pueden modificar, borrar y compartir entre varios usuarios.

Calendario y lista de calendarios

La colección Calendarios representa todos los calendarios existentes. Se puede usar para crear y borrar calendarios. También puedes recuperar o establecer propiedades globales compartidas entre todos los usuarios con acceso a un calendario. Por ejemplo, el título de un calendario y la zona horaria predeterminada son propiedades globales.

CalendarList es una colección de todas las entradas de calendario que un usuario agregó a su lista (se muestra en el panel izquierdo de la IU web). Puedes usarlo para agregar y quitar calendarios existentes hacia o desde la lista de usuarios. También puedes usarlo para recuperar y establecer valores de propiedades de calendario específicas del usuario, como los recordatorios predeterminados. Otro ejemplo es el color de primer plano, ya que diferentes usuarios pueden tener diferentes colores configurados para el mismo calendario.

En la siguiente tabla, se compara el significado de las operaciones para las dos colecciones:

Operación Calendarios CalendarList
insert Crea un nuevo calendario secundario. De forma predeterminada, este calendario también se agrega a la lista de calendarios del creador. Inserta un calendario existente en la lista del usuario.
delete Borra un calendario secundario. Quita un calendario de la lista del usuario.
get Recupera metadatos del calendario, p.ej., título y zona horaria. Recupera metadatos además de personalizaciones específicas del usuario, como los recordatorios de color o de anulación.
patch/update Modifica los metadatos del calendario. Modifica las propiedades del calendario específicas del usuario.

Eventos recurrentes

Algunos eventos ocurren varias veces en un horario regular, como reuniones semanales, cumpleaños y días feriados. Además de tener horas de inicio y finalización diferentes, estos eventos repetidos suelen ser idénticos.

Los eventos se denominan recurrentes si se repiten de acuerdo con un programa definido. Los eventos únicos no son recurrentes y ocurren una sola vez.

Regla de recurrencia

La programación de un evento recurrente se define en dos partes:

  • sus campos de inicio y finalización (que definen el primer caso, como si fuera solo un evento único)

  • Su campo de recurrencia (que define cómo se debe repetir el evento en el tiempo).

El campo de recurrencia contiene un array de cadenas que representan una o varias propiedades RRULE, RDATE o EXDATE, como se define en RFC 5545.

La propiedad RRULE es la más importante, ya que define una regla regular para repetir el evento. Tiene varios componentes. Algunos de ellos son los siguientes:

  • FREQ: Es la frecuencia con la que se debe repetir el evento (como DAILY o WEEKLY). Es obligatorio.

  • INTERVAL: Funciona junto con FREQ para especificar la frecuencia con la que se debe repetir el evento. Por ejemplo, FREQ=DAILY;INTERVAL=2 significa una vez cada dos días.

  • COUNT: Es la cantidad de veces que se debe repetir este evento.

  • UNTIL: Es la fecha o la hora hasta la que se debe repetir el evento (inclusive).

  • BYDAY: Indica los días de la semana en los que se debe repetir el evento (SU, MO, TU, etcétera). Otros componentes similares incluyen BYMONTH, BYYEARDAY y BYHOUR.

La propiedad RDATE especifica fechas o horarios adicionales en los que deberían ocurrir los eventos. Por ejemplo, RDATE;VALUE=DATE:19970101,19970120 Úsalo para agregar casos adicionales que no estén cubiertos por RRULE.

La propiedad EXDATE es similar a RDATE, pero especifica las fechas o las horas en las que el evento no debería ocurrir. Es decir, esos casos deben excluirse. Esto debe apuntar a una instancia válida generada por la regla de recurrencia.

EXDATE y RDATE pueden tener una zona horaria y deben ser fechas (no fechas-horas) para los eventos que duran todo el día.

Cada una de las propiedades puede aparecer en el campo de recurrencia varias veces. La recurrencia se define como la unión de todas las reglas RRULE y RDATE, menos las excluidas por todas las reglas EXDATE.

Estos son algunos ejemplos de eventos recurrentes:

  1. Un evento que ocurre desde las 6:00 a.m. hasta las 7:00 a.m. todos los martes y viernes, a partir del 15 de septiembre de 2015 y que finaliza después del quinto evento el 29 de septiembre:

    ...
    "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. Un evento de todo el día que comienza el 1 de junio de 2015 y se repite cada 3 días durante todo el mes, sin incluir el 10 de junio, pero incluidos el 9 y el 11 de junio:

    ...
    "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"
    ],
    …
    

Instancias y excepciones

Un evento recurrente consta de varias instancias: sus casos particulares en diferentes momentos. Estas instancias actúan como eventos en sí mismas.

Las modificaciones de los eventos recurrentes pueden afectar a todo el evento recurrente (y a todas sus instancias) o solo a instancias individuales. Las instancias que difieren de su evento recurrente principal se denominan excepciones.

Por ejemplo, una excepción puede tener un resumen diferente, una hora de inicio diferente o asistentes adicionales invitados solo a esa instancia. También puedes cancelar una instancia por completo sin quitar el evento recurrente (las cancelaciones de instancias se reflejan en el evento status).

Puedes encontrar aquí ejemplos para trabajar con instancias y eventos recurrentes mediante la API del Calendario de Google.

Zonas horarias

Una zona horaria especifica una región que respeta una hora estándar uniforme. En la API del Calendario de Google, debes especificar las zonas horarias con los identificadores de la zona horaria de IANA.

Puedes establecer la zona horaria tanto para los calendarios como para los eventos. En las siguientes secciones, se describen los efectos de estas configuraciones.

Zona horaria del calendario

La zona horaria del calendario también se conoce como zona horaria predeterminada debido a las implicancias que tiene en los resultados de las consultas. La zona horaria del calendario afecta la forma en que los métodos events.get(), events.list() y events.instances() interpretan o presentan los valores de tiempo.

Conversión de la zona horaria del resultado de la consulta
Los resultados de los métodos get(), list() y instances() se muestran en la zona horaria que especificas en el parámetro timeZone. Si omites este parámetro, todos estos métodos usarán la zona horaria del calendario como predeterminada.
Haz coincidir los eventos de todo el día con las consultas separadas por tiempo
Los métodos list() y instances() te permiten especificar filtros de hora de inicio y finalización, y el método muestra instancias que se encuentran en el rango especificado. La zona horaria del calendario se usa para calcular las horas de inicio y finalización de los eventos de todo el día a fin de determinar si se encuentran dentro de la especificación del filtro.

Zona horaria del evento

Las instancias de eventos tienen una hora de inicio y de finalización. La especificación de estos horarios puede incluir la zona horaria. Puedes especificar la zona horaria de varias maneras. Las siguientes indican la misma hora:

  • Incluye un desplazamiento de zona horaria en el campo dateTime, por ejemplo, 2017-01-25T09:00:00-0500.
  • Especifica la hora sin desplazamiento, por ejemplo, 2017-01-25T09:00:00, y deja el campo timeZone vacío (esto usa implícitamente la zona horaria predeterminada).
  • Especifica la hora sin desplazamiento, por ejemplo, 2017-01-25T09:00:00, pero usa el campo timeZone para indicar la zona horaria.

Si lo prefieres, también puedes especificar las horas de los eventos en UTC:

  • Especifica la hora en UTC: 2017-01-25T14:00:00Z o usa un desplazamiento cero 2017-01-25T14:00:00+0000.

La representación interna de la hora del evento es la misma en todos estos casos, pero cuando se configura el campo timeZone, se adjunta una zona horaria al evento, al igual que cuando configuras una zona horaria del evento con la IU del Calendario:

Fragmento de la captura de pantalla que muestra la zona horaria de un evento

Zona horaria del evento recurrente

Para los eventos recurrentes, se debe especificar siempre una zona horaria única. Es necesario para expandir la recurrencia del evento.