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 el resumen, la zona horaria predeterminada, la ubicación, etcétera. 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 a un período o fecha 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 el resumen, la descripción, la ubicación, el estado, los recordatorios, los archivos adjuntos, etcétera.

Tipos de eventos

El Calendario de Google admite eventos únicos y recurrentes:

• Un evento único representa una ocurrencia única.
• Un evento recurrente define varios casos.

Los eventos también pueden ser programados o de todo el día:

• Un evento cronometrado ocurre entre dos momentos específicos. Los eventos cronometrados 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 consecutiva de días. 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 de 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. Por lo general, un asistente es el calendario principal de un usuario invitado.

En el siguiente diagrama, se muestra la relación conceptual entre los calendarios, los 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 exista la cuenta, el usuario nunca podrá borrar su calendario principal ni dejar de ser su propietario. Sin embargo, se puede compartir con otros usuarios.

Además del calendario principal, puedes crear explícitamente la cantidad de calendarios que desees. Estos calendarios se pueden modificar, borrar y compartir entre varios usuarios.

Calendario y lista de calendarios

La colección Calendars 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 y la zona horaria predeterminada de un calendario 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 de la lista de usuarios. También lo usas para recuperar y establecer los valores de las propiedades del 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 establecidos 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 calendario secundario nuevo. 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., el título y la zona horaria.	Recupera metadatos y personalizaciones específicas del usuario, como el color o los recordatorios de reemplazo.
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 las reuniones semanales, los cumpleaños y los días festivos. Además de tener diferentes horas de inicio y finalización, estos eventos repetidos suelen ser idénticos.

Los eventos se denominan recurrentes si se repiten según un programa definido. Los eventos únicos no son recurrentes y ocurren solo una vez.

Regla de recurrencia

El programa de un evento recurrente se define en dos partes:

• Sus campos de inicio y finalización (que definen la primera ocurrencia, como si se tratara de un solo evento independiente)

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

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

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

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

• INTERVAL: Funciona junto con FREQ para especificar con qué frecuencia 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 fecha y hora hasta la que se debe repetir el evento (inclusive).

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

La propiedad RDATE especifica fechas o fechas y horas adicionales en las que deben ocurrir los eventos. Por ejemplo, RDATE;VALUE=DATE:19970101,19970120 Úsalo para agregar casos adicionales que no cubre el RRULE.

La propiedad EXDATE es similar a RDATE, pero especifica fechas o fechas y horas en las que no debe ocurrir el evento. Es decir, se deben excluir esas ocurrencias. 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 y horas) para los eventos de todo el día.

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

Estos son algunos ejemplos de eventos recurrentes:

1. Un evento que ocurre de 6 a.m. a 7 a.m. todos los martes y viernes a partir del 15 de septiembre de 2015 y que se detiene 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, excepto 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 ocurrencias particulares en diferentes momentos. Estas instancias actúan como eventos en sí.

Las modificaciones de 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).

Aquí puedes encontrar ejemplos de cómo trabajar con eventos y repeticiones recurrentes a través de la API de Google Calendar.

Zonas horarias

Una zona horaria especifica una región que observa una hora estándar uniforme. En la API de Calendar de Google, las zonas horarias se especifican con identificadores de zonas horarias de IANA.

Puedes configurar la zona horaria para los calendarios y los eventos. En las siguientes secciones, se describen los efectos de estos parámetros de configuración.

Zona horaria del calendario

La zona horaria del calendario también se conoce como la zona horaria predeterminada debido a sus implicaciones en los resultados de la búsqueda. 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 zona horaria del resultado de la búsqueda

Los resultados de los métodos get(), list() y instances() se devuelven 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 valor predeterminado.

Cómo hacer coincidir eventos de todo el día con búsquedas con intervalos de tiempo

Los métodos list() y instances() te permiten especificar filtros de hora de inicio y finalización, y el método devuelve instancias que se encuentran dentro del 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 y 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 una hora de finalización. La especificación de estas horas puede incluir la zona horaria. Puedes especificar la zona horaria de varias maneras. Todas las siguientes opciones especifican 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 desfase, 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 compensación, por ejemplo, 2017-01-25T09:00:00, pero usa el campo timeZone para especificar la zona horaria.

También puedes especificar las horas de los eventos en UTC si lo prefieres:

• 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 configurar el campo timeZone adjunta una zona horaria al evento, al igual que cuando configuras una zona horaria del evento con la IU del Calendario:

Zona horaria del evento recurrente

En el caso de los eventos recurrentes, siempre se debe especificar una sola zona horaria. Se necesita para expandir las recurrencias del evento.