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 se pueden compartir con otras personas. Los calendarios principales son propiedad de su cuenta de usuario asociada, mientras que los demás calendarios son propiedad de un solo propietario de datos.

Eventos

Un evento es un objeto asociado con una fecha o un período 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 varias ocurrencias.

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

• Un evento programado ocurre entre dos puntos específicos en el tiempo. Los eventos programados 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.

El inicio y el final del evento deben ser programados o de todo el día. Por ejemplo, no es válido especificar start.date y end.dateTime.

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 ni "desvincular" su calendario principal. Sin embargo, se puede compartir con otros usuarios.

Además del calendario principal, puedes crear explícitamente cualquier cantidad de otros calendarios. Estos calendarios se pueden modificar, borrar y compartir con otras personas. Estos calendarios tienen un solo propietario de datos con los privilegios más altos, incluido el derecho exclusivo de borrar el calendario. No se puede degradar el nivel de acceso del propietario de los datos. Inicialmente, el propietario de los datos se determina como el usuario que creó el calendario. Sin embargo, la propiedad de los datos se puede transferir en la IU del Calendario de Google.

Importante: Cuando crees un calendario, te recomendamos que tu app se autentique como el propietario de datos previsto del calendario. Puedes usar la delegación de autoridad de todo el dominio para permitir que las aplicaciones actúen en nombre de un usuario específico. No uses una cuenta de servicio para la autenticación. Si usas una cuenta de servicio para la autenticación, la cuenta de servicio es el propietario de los datos, lo que puede generar un comportamiento inesperado. Por ejemplo, si una cuenta de servicio es el propietario de los datos, no se puede transferir la propiedad de los datos.

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.

El CalendarList es una colecció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 usarla para agregar y quitar calendarios existentes de la lista de usuarios. También la 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.

Nota: El propietario de los datos de un calendario no puede quitar este calendario de su lista de calendarios.

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

Operación	Calendars	CalendarList
insert	Crea un calendario secundario nuevo. Este calendario también se agrega a la lista de calendarios del creador y no se puede quitar, a menos que se borre o transfiera.	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, por ejemplo, el título y la zona horaria.	Recupera los metadatos más la personalización específica 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. 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 horario definido. Los eventos únicos no son recurrentes y ocurren solo una vez.

Regla de recurrencia

El horario 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 evento único independiente) y

• Su campo de recurrencia (que define cómo se debe repetir el evento a lo largo del tiempo)

El campo de recurrencia contiene un array de cadenas que representan una o varias RRULE, RDATE o EXDATE propiedades como se define 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 (como 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.

  Puedes usar COUNT o UNTIL para especificar el final de la recurrencia del evento. No uses ambos en la misma regla.

• 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 incluyen BYMONTH, BYYEARDAY y BYHOUR.

La propiedad RDATE especifica fechas o fechas y horas adicionales en las que deben ocurrir las instancias del evento. Por ejemplo, RDATE;VALUE=DATE:19970101,19970120. Usa esta opción para agregar instancias adicionales que no estén cubiertas por RRULE.

La propiedad EXDATE es similar a RDATE, pero especifica fechas o fechas y horas en las que el evento no debe ocurrir. Es decir, esas instancias 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 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 excluyen 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 de la quinta ocurrencia 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.

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 superior 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 recurrentes y sus instancias a través de la API del Calendario de Google aquí.

Zonas horarias

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

Puedes establecer la zona horaria para calendarios y 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 la 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 tiempo.

Conversión de zona horaria de los resultados de la consulta

Los resultados de los get(), list() y instances() métodos se muestran en la zona horaria que especificas en el timeZone parámetro. 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 consultas con corchetes de tiempo

Los list() y instances() métodos te permiten especificar filtros de hora de inicio y finalización, y el método muestra las 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 para 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. Todas las siguientes 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 desplazamiento, por ejemplo, 2017-01-25T09:00:00, dejando vacío el campo timeZone (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.

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 estableces una zona horaria del evento con la IU del Calendario:

Para eventos únicos, puedes especificar diferentes zonas horarias para las horas de inicio y finalización de un evento. (Esto puede ayudar con eventos, como viajes, que realmente comienzan y terminan en diferentes zonas horarias). Para eventos recurrentes, consulta lo siguiente.

Zona horaria del evento recurrente

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