Calendari ed eventi

Questa guida descrive i calendari, gli eventi e la loro relazione.

Calendari

Un calendario è una raccolta di eventi correlati, insieme a metadati aggiuntivi come riepilogo, fuso orario predefinito, località e così via. Ogni calendario è identificato da un ID, che è un indirizzo email. I calendari possono essere condivisi con altri utenti. I calendari principali sono di proprietà dell'account utente associato, mentre gli altri calendari sono di proprietà di un singolo proprietario dei dati.

Eventi

Un evento è un oggetto associato a una data o a un intervallo di tempo specifici. Gli eventi sono identificati da un ID univoco. Oltre a una data e un'ora di inizio e di fine, gli eventi contengono altri dati come riepilogo, descrizione, località, stato, promemoria, allegati e così via.

Tipi di eventi

Google Calendar supporta eventi singoli e ricorrenti:

  • Un evento singolo rappresenta un'occorrenza unica.
  • Un evento ricorrente definisce più occorrenze.

Gli eventi possono anche essere programmati o che durano tutto il giorno:

  • Un evento programmato si verifica tra due momenti specifici. Gli eventi programmati utilizzano i campi start.dateTime e end.dateTime per specificare quando si verificano.
  • Un evento che dura tutto il giorno si estende per un'intera giornata o per una serie di giorni consecutivi. Gli eventi che durano tutto il giorno utilizzano i campi start.date e end.date per specificare quando si verificano. Tieni presente che il campo del fuso orario non ha alcun significato per gli eventi che durano tutto il giorno.

Organizzatori

Gli eventi hanno un singolo organizzatore , ovvero il calendario contenente la copia principale dell'evento. Gli eventi possono anche avere più invitati. Un partecipante è in genere il calendario principale di un utente invitato.

Il seguente diagramma mostra la relazione concettuale tra calendari, eventi e altri elementi correlati:

Calendari principali e altri calendari

Un calendario principale è un tipo speciale di calendario associato a un singolo account utente. Questo calendario viene creato automaticamente per ogni nuovo account utente e il suo ID corrisponde in genere all'indirizzo email principale dell'utente. Finché l'account esiste, il calendario principale non può mai essere eliminato o "non di proprietà" dell'utente. Tuttavia, può comunque essere condiviso con altri utenti.

Oltre al calendario principale, puoi creare esplicitamente un numero qualsiasi di altri calendari. Questi calendari possono essere modificati, eliminati e condivisi con altri utenti. Questi calendari hanno un singolo proprietario dei dati con i privilegi più elevati, incluso il diritto esclusivo di eliminare il calendario. Il livello di accesso del proprietario dei dati non può essere ridotto. Il proprietario dei dati viene inizialmente determinato come l'utente che ha creato il calendario, ma la proprietà dei dati può essere trasferita nell'interfaccia utente di Google Calendar.

Calendario ed elenco dei calendari

La raccolta Calendars rappresenta tutti i calendari esistenti. Può essere utilizzata per creare ed eliminare calendari. Puoi anche recuperare o impostare proprietà globali condivise da tutti gli utenti con accesso a un calendario. Ad esempio, il titolo e il fuso orario predefinito di un calendario sono proprietà globali.

Il CalendarList è una raccolta di tutte le voci di calendario che un utente ha aggiunto al proprio elenco (mostrato nel riquadro a sinistra dell'interfaccia utente web). Puoi utilizzarla per aggiungere e rimuovere calendari esistenti dall'elenco degli utenti. Puoi anche utilizzarla per recuperare e impostare i valori delle proprietà del calendario specifiche dell'utente, ad esempio i promemoria predefiniti. Un altro esempio è il colore di primo piano, poiché utenti diversi possono avere colori diversi impostati per lo stesso calendario.

La tabella seguente confronta il significato delle operazioni per le due raccolte:

Operazione Calendars CalendarList
insert Crea un nuovo calendario secondario. Questo calendario viene aggiunto anche all' elenco dei calendari del creatore e non può essere rimosso, a meno che il calendario non venga eliminato o trasferito. Inserisce un calendario esistente nell'elenco dell'utente.
delete Elimina un calendario secondario. Rimuove un calendario dall'elenco dell'utente.
get Recupera i metadati del calendario, ad es. titolo, fuso orario. Recupera i metadati più la personalizzazione specifica dell'utente ad esempio il colore o i promemoria di override.
patch/update Modifica i metadati del calendario. Modifica le proprietà del calendario specifiche dell'utente.

Eventi ricorrenti

Alcuni eventi si verificano più volte con una pianificazione regolare, ad esempio riunioni settimanali, compleanni e festività. Oltre ad avere orari di inizio e di fine diversi, questi eventi ripetuti sono spesso identici.

Gli eventi vengono chiamati ricorrenti se si ripetono secondo una pianificazione definita. Gli eventi singoli non sono ricorrenti e si verificano una sola volta.

Regola di ricorrenza

La pianificazione di un evento ricorrente è definita in due parti:

  • I campi di inizio e fine (che definiscono la prima occorrenza, come se si trattasse di un singolo evento autonomo) e

  • Il campo di ricorrenza (che definisce la modalità di ripetizione dell'evento nel tempo).

Il campo di ricorrenza contiene un array di stringhe che rappresentano una o più proprietà RRULE, RDATE o EXDATE come definito in RFC 5545.

La proprietà RRULE è la più importante perché definisce una regola regolare per la ripetizione dell'evento. È composta da diversi componenti. Alcuni di questi sono:

  • FREQ : la frequenza con cui l'evento deve essere ripetuto (ad esempio DAILY o WEEKLY). Obbligatorio.

  • INTERVAL : funziona insieme a FREQ per specificare la frequenza con cui l'evento deve essere ripetuto. Ad esempio, FREQ=DAILY;INTERVAL=2 significa una volta ogni due giorni.

  • COUNT : il numero di volte in cui questo evento deve essere ripetuto.

  • UNTIL : la data o l'ora fino alla quale l'evento deve essere ripetuto (inclusa).

  • BYDAY : i giorni della settimana in cui l'evento deve essere ripetuto (SU, MO, TU e così via). Altri componenti simili includono BYMONTH, BYYEARDAY e BYHOUR.

La proprietà RDATE specifica date o ore aggiuntive in cui devono verificarsi le occorrenze dell'evento. Ad esempio, RDATE;VALUE=DATE:19970101,19970120. Utilizza questa opzione per aggiungere occorrenze aggiuntive non coperte da RRULE.

La proprietà EXDATE è simile a RDATE, ma specifica le date o le ore in cui l'evento non deve verificarsi. Ovvero, queste occorrenze devono essere escluse. Questo deve puntare a un'istanza valida generata dalla regola di ricorrenza.

EXDATE e RDATE possono avere un fuso orario e devono essere date (non ore) per gli eventi che durano tutto il giorno.

Ciascuna delle proprietà può essere presente più volte nel campo di ricorrenza. La ricorrenza è definita come l'unione di tutte le regole RRULE e RDATE, meno quelle escluse da tutte le regole EXDATE.

Ecco alcuni esempi di eventi ricorrenti:

  1. Un evento che si svolge dalle 6:00 alle 7:00 ogni martedì e venerdì a partire dal 15 settembre 2015 e che si interrompe dopo la quinta occorrenza il 29 settembre:

    ...
"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 che dura tutto il giorno a partire dal 1° giugno 2015 e che si ripete ogni 3 giorni per tutto il mese, escluso il 10 giugno ma inclusi il 9 e l'11 giugno:

    ...
"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"
],
…

Istanze ed eccezioni

Un evento ricorrente è costituito da diverse istanze: le sue occorrenze specifiche in momenti diversi. Queste istanze fungono da eventi stessi.

Le modifiche agli eventi ricorrenti possono interessare l'intero evento ricorrente (e tutte le relative istanze) o solo le singole istanze. Le istanze che differiscono dall'evento ricorrente principale vengono chiamate eccezioni.

Ad esempio, un'eccezione può avere un riepilogo diverso, un'ora di inizio diversa o invitati aggiuntivi invitati solo a quell'istanza. Puoi anche annullare completamente un' istanza senza rimuovere l'evento ricorrente (gli annullamenti delle istanze si riflettono nello stato dell'evento status).

Esempi di come utilizzare gli eventi e le istanze ricorrenti tramite l' API Google Calendar sono disponibili qui.

Fusi orari

Un fuso orario specifica una regione che osserva un orario standard uniforme. Nell'API Google Calendar, i fusi orari vengono specificati utilizzando gli identificatori dei fusi orari IANA.

Puoi impostare il fuso orario sia per i calendari sia per gli eventi. Le sezioni seguenti descrivono gli effetti di queste impostazioni.

Fuso orario del calendario

Il fuso orario del calendario è noto anche come fuso orario predefinito a causa delle sue implicazioni per i risultati delle query. Il fuso orario del calendario influisce sul modo in cui i valori temporali vengono interpretati o presentati dai events.get(), events.list() e events.instances() metodi.

Conversione del fuso orario dei risultati delle query
I risultati dei metodi get(), list() e instances() vengono restituiti nel fuso orario specificato nel parametro timeZone. Se ometti questo parametro, questi metodi utilizzano tutti il fuso orario del calendario come predefinito.
Corrispondenza degli eventi che durano tutto il giorno con le query con intervalli di tempo
I list() e instances() consentono di specificare i filtri dell'ora di inizio e di fine, con il metodo che restituisce le istanze che rientrano nell'intervallo specificato. Il fuso orario del calendario viene utilizzato per calcolare l'ora di inizio e di fine degli eventi che durano tutto il giorno per determinare se rientrano nella specifica del filtro.

Fuso orario dell'evento

Le istanze degli eventi hanno un'ora di inizio e di fine; la specifica di queste ore può includere il fuso orario. Puoi specificare il fuso orario in diversi modi; i seguenti specificano tutti la stessa ora:

  • Includi un offset del fuso orario nel campo dateTime, ad esempio 2017-01-25T09:00:00-0500.
  • Specifica l'ora senza offset, ad esempio 2017-01-25T09:00:00, lasciando vuoto il campo timeZone (in questo modo viene utilizzato implicitamente il fuso orario predefinito).
  • Specifica l'ora senza offset, ad esempio 2017-01-25T09:00:00, ma utilizza il campo timeZone per specificare il fuso orario.

Se preferisci, puoi anche specificare le ore degli eventi in UTC:

  • Specifica l'ora in UTC: 2017-01-25T14:00:00Z o utilizza un offset zero 2017-01-25T14:00:00+0000.

La rappresentazione interna dell'ora dell'evento è la stessa in tutti questi casi, ma l'impostazione del campo timeZone associa un fuso orario all'evento, proprio come quando imposti un fuso orario dell'evento utilizzando l'interfaccia utente di Calendar:

Frammento di screenshot che mostra il fuso orario di un evento

Fuso orario degli eventi ricorrenti

Per gli eventi ricorrenti deve essere sempre specificato un singolo fuso orario. È necessario per espandere le ricorrenze dell'evento.