Calendarios y eventos

En esta guía, se describen calendarios, 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 horas específicos. Los eventos se identifican con un ID único. Además de la 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 evento único representa un caso único.
• Un evento recurrente define varios casos.

Los eventos también pueden ser programados o que duran 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 que dura todo el día abarca un día entero o una serie de días consecutivos. En los eventos de todo el día, se 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 es generalmente 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. Siempre que la cuenta exista, el usuario nunca podrá borrar ni quitar el calendario principal. Sin embargo, aún se puede compartir con otros usuarios.

Además del calendario principal, puedes crear explícitamente otros calendarios, los cuales 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 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 calendarios existentes a la lista de usuarios y quitarlos de ella. También se usa para recuperar y establecer los valores de las propiedades del calendario específicas de los usuarios, 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 los metadatos del calendario (p.ej., el título y la zona horaria).	Recupera los metadatos además de las personalizaciones específicas del usuario, como el color o los recordatorios 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 festivos. Aparte de tener horas de inicio y finalización diferentes, 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

La agenda de un evento recurrente se define en dos partes:

• sus campos de inicio y finalización (que definen el primer caso, como si se tratara de un solo evento independiente)

• El campo de recurrencia (que define cómo debe repetirse el evento a lo largo del tiempo)

El campo de recurrencia contiene un array de cadenas que representan una o varias propiedades RRULE, RDATE o EXDATE, según 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. Estos son algunos de ellos:

• FREQ: Es la frecuencia con la que se debe repetir el evento (como DAILY o WEEKLY). 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: Indica 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: 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 y horas adicionales en las que deben ocurrir los casos del evento. 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 fechas y horas en las que no debería ocurrir el evento. Es decir, deben excluirse esos casos. 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 ocurrir dentro del campo de recurrencia varias veces. La recurrencia se define como la unión de todas las reglas RRULE y RDATE, menos las que excluyan todas las reglas EXDATE.

Estos son algunos ejemplos de eventos recurrentes:

1. Un evento que tiene lugar 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 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 que dura todo el día y que comienza el 1 de junio de 2015 y se repite cada 3 días en 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 casos particulares en diferentes momentos. Estas instancias actúan como eventos en sí mismas.

Las modificaciones de eventos recurrentes pueden afectar a todo el evento recurrente (y 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 o una hora de inicio diferente, o bien 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í encontrarás ejemplos de cómo trabajar con instancias y eventos recurrentes a través de la API del Calendario de Google.

Zonas horarias

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

Puedes configurar la zona horaria tanto para calendarios como para eventos. En las siguientes secciones, se describen los efectos de esta configuración.

Zona horaria del calendario

La zona horaria del calendario también se conoce como zona horaria predeterminada debido a sus implicaciones para los resultados de la consulta. 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 hora.

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 usan la zona horaria del calendario como predeterminada.

Hacer coincidir los eventos que duran todo el día con las búsquedas desglosadas en intervalos de tiempo

Los métodos list() y instances() te permiten especificar los 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 que duran todo el día y, así, determinar si cumplen con 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 estas horas puede incluir la zona horaria. Puedes especificar la zona horaria de varias maneras. A continuación, se especifica 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 ajuste (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 especificar 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 2017-01-25T14:00:00+0000 de desplazamiento cero.

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:

Zona horaria del evento recurrente

Para los eventos recurrentes, siempre se debe especificar una única zona horaria. Es necesaria para expandir las recurrencias del evento.