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 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 con una fecha o un intervalo de horas 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 un caso único.
• Un evento recurrente define varias ocurrencias.

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

• Un evento programado ocurre entre dos momentos específicos. Los eventos programados usan los campos start.dateTime y end.dateTime para especificar cuándo ocurren.
• Un evento 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 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. 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 la cuenta exista, 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 de forma explícita cualquier cantidad de otros 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 y la zona horaria predeterminada de un calendario son propiedades globales.

CalendarList es una recopilación de todas las entradas de calendario que un usuario agregó a su lista (que 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 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 los diferentes usuarios pueden establecer diferentes colores 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 más la personalización específica del usuario, como el color o la anulación de recordatorios.
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 habitual, como reuniones semanales, cumpleaños y feriados. 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 programación de un evento recurrente se define en dos partes:

• Sus campos de inicio y finalización (que definen la primera ocurrencia, como si fuera 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 define en la 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. 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 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: Son los 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 horas adicionales en las que deben 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 fechas o horas en las que el evento no debe ocurrir. Es decir, se deben excluir 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 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 que excluyen 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 de todo el día que comienza el 1 de junio de 2015 y se repite cada 3 días durante el mes, excepto el 10 de junio, pero incluye 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.

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

Por ejemplo, una excepción puede tener un resumen, una hora de inicio 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 instancias y eventos 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 Calendario de Google, especificas las zonas horarias con los identificadores de zona horaria de IANA.

Puedes establecer 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 para 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 zona horaria de los resultados 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.

Cómo hacer coincidir eventos de todo el día con búsquedas con corchetes 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 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 finalización. La especificación de estas horas puede incluir la zona horaria. Puedes especificar la zona horaria de varias maneras. 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 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 compensación, 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 desplazamiento de 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 de un 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. Es necesario para expandir las recurrencias del evento.