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 por 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ífico. Los eventos se identifican con un ID único. Además de un comienzo y fecha y hora de finalización, los eventos contienen otros datos, como resumen, descripción, ubicación, estado, recordatorios, archivos adjuntos, etc.

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. Eventos programados usa los campos start.dateTime y end.dateTime para especificar cuándo de que ocurran cambios.
• Un evento que dura todo el día abarca un día entero o una serie de días consecutivos. Todo el día Los eventos 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 participantes. Un asistente es generalmente el calendario principal de un usuario invitado.

El siguiente diagrama 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 a un único 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 el existe una cuenta, el calendario principal nunca se puede eliminar ni ser de por el usuario. Sin embargo, aún 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 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 usuarios con acceso a un calendario. Por ejemplo, el título y la configuración predeterminada y zona horaria son propiedades globales.

CalendarList es una 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 existentes calendarios a/desde la lista de usuarios. También se usa para recuperar y configurar valores de 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 colores diferentes 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 agregado 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. título, zona horaria.	Recupera metadatos además de personalizaciones específicas del usuario. como recordatorios de color o 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 cronograma regular, como las 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 este solo un evento independiente) y

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

El campo de recurrencia contiene un conjunto de cadenas que representan una o varias Propiedades RRULE, RDATE o EXDATE, según se define en RFC 5,545

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: Indica la frecuencia con la que se debe repetir el evento (por ejemplo, DAILY o WEEKLY). Obligatorio.

• INTERVAL: Funciona junto con FREQ para especificar la frecuencia del evento. debe repetirse. Por ejemplo, FREQ=DAILY;INTERVAL=2 significa que 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.). Otros componentes similares incluyen BYMONTH, BYYEARDAY y BYHOUR

La propiedad RDATE especifica fechas y horas adicionales en las que el evento de cuándo deberían ocurrir. 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. cuándo no debe ocurrir el evento. Es decir, esos casos deben ser excluidos. 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 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 el las que excluyen todas las reglas EXDATE.

Estos son algunos ejemplos de eventos recurrentes:

1. Un evento que se lleva a cabo desde las 6:00 a.m. hasta las 7:00 a.m. todos los martes y viernes a partir del desde el 15 de septiembre de 2015 y finalizará después del quinto caso 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. Comienza el 1 de junio de 2015 y se repite cada tres días. a lo largo del 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 eventos recurrentes pueden afectar un 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 diferente o asistentes adicionales invitados solo a esa instancia. También puedes cancelar un por completo sin quitar el evento recurrente (las cancelaciones de instancias se reflejan en el registro status)

Ejemplos de cómo trabajar con instancias y eventos recurrentes a través de la Puedes encontrar la API de Calendario de Google aquí.

Zonas horarias

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

Puedes configurar la zona horaria tanto para calendarios como para eventos. Las siguientes secciones describir 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 la consulta. La zona horaria del calendario los valores de tiempo son interpretados o presentados por el events.get(): events.list() y métodos events.instances().

Conversión de la zona horaria del resultado de la consulta

Resultados del get(), list() y instances() se muestran en la zona horaria que especificaste en el parámetro timeZone parámetro. Si omites este parámetro, todos estos métodos usan el esquema zona horaria como la predeterminada.

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

El list() y instances() te permiten especificar filtros de hora de inicio y finalización, con el método mostrar instancias que caen 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 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 de finalización. la especificación para estos tiempos pueden incluir la zona horaria. Puedes especificar la zona horaria de varias maneras: el 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 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 establecer el campo timeZone adjunta una zona horaria al evento, al igual que cuando configuras la zona horaria del evento con la función IU:

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.