Questa guida descrive i calendari, gli eventi e le loro relazioni reciproche.
Calendari
Un calendario è una raccolta di eventi correlati, insieme a metadati aggiuntivi come riepilogo, fuso orario predefinito, posizione e così via. Ogni calendario è identificato da un ID che è un indirizzo email. I calendari possono avere più proprietari.
Eventi
Un evento è un oggetto associato a un intervallo di date o ore specifico. 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, posizione, stato, promemoria, allegati e così via.
Tipi di eventi
Google Calendar supporta eventi singoli e ricorrenti:
- Un singolo evento rappresenta un'occorrenza unica.
- Un evento ricorrente definisce più occorrenze.
Gli eventi possono anche essere a tempo o tutto il giorno:
- Un evento timer si verifica tra due momenti specifici. Gli eventi a tempo
utilizzano i campi
start.dateTime
eend.dateTime
per specificare quando si verificano. - Un evento di tutto il giorno copre un giorno intero o una serie di giorni consecutivi. Gli eventi che durano tutto il giorno utilizzano i campi
start.date
eend.date
per specificare quando si verificano. Tieni presente che il campo del fuso orario non ha alcuna rilevanza per gli eventi che durano tutto il giorno.
Organizzatori
Gli eventi hanno un singolo organizzatore, ovvero il calendario che contiene la copia principale dell'evento. Gli eventi possono anche avere più partecipanti. Un partecipante è di solito 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 di solito corrisponde all'indirizzo email principale dell'utente. Finché l'account esiste, il calendario principale non può mai essere eliminato o "senza proprietà" dall'utente. Tuttavia, potrà essere comunque 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 tra più utenti.
Calendario e elenco calendari
La raccolta Calendari rappresenta tutti i calendari esistenti. Può essere usato per creare ed eliminare i calendari. Puoi inoltre recuperare o impostare le proprietà globali condivise tra tutti gli utenti con accesso a un calendario. Ad esempio, il titolo e il fuso orario predefinito di un calendario sono proprietà globali.
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 utilizzarlo per aggiungere e rimuovere calendari esistenti all'elenco degli utenti. Puoi utilizzarlo anche per recuperare e impostare i valori delle proprietà del calendario specifiche dell'utente, come i promemoria predefiniti. Un altro esempio è il colore in primo piano, dato che utenti diversi possono impostare colori diversi per lo stesso calendario.
La tabella seguente mette a confronto il significato delle operazioni per le due raccolte:
Operazione | Calendari | CalendarList |
---|---|---|
insert |
Crea un nuovo calendario secondario. Per impostazione predefinita, questo calendario viene aggiunto anche all'elenco di calendari dell'autore. | 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 esempio titolo, fuso orario. | Recupera i metadati oltre a personalizzazioni specifiche dell'utente come il colore o l'override dei promemoria. |
patch /update |
Modifica i metadati del calendario. | Modifica le proprietà del calendario specifiche dell'utente. |
Eventi ricorrenti
Alcuni eventi si svolgono più volte con una programmazione regolare, come riunioni settimanali, compleanni e festività. A parte l'ora di inizio e l'ora di fine diverse, questi eventi ripetuti sono spesso identici.
Gli eventi sono detti ricorrenti se si ripetono in base a una pianificazione definita. Gli eventi singoli non sono ricorrenti e si verificano solo una 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 fosse un singolo evento autonomo) e
Il suo campo di ricorrenza (che definisce la modalità di ripetizione dell'evento nel tempo).
Il campo 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 in quanto definisce una regola regolare per
ripetere l'evento. È composto da diversi componenti. Alcuni di questi sono:
FREQ
: la frequenza con cui deve essere ripetuto l'evento, ad esempioDAILY
oWEEKLY
. Campo obbligatorio.INTERVAL
- Funziona insieme aFREQ
per specificare la frequenza di ripetizione dell'evento. Ad esempio,FREQ=DAILY;INTERVAL=2
indica una volta ogni due giorni.COUNT
: numero di volte in cui l'evento deve essere ripetuto.UNTIL
: la data o la data e l'ora fino a quando l'evento deve essere ripetuto (incluse).BYDAY
: giorni della settimana in cui l'evento deve essere ripetuto (SU
,MO
,TU
e così via). Altri componenti simili includonoBYMONTH
,BYYEARDAY
eBYHOUR
.
La proprietà RDATE
specifica date o ore aggiuntive in cui devono verificarsi le occorrenze degli eventi. Ad esempio, RDATE;VALUE=DATE:19970101,19970120
.
Utilizza questo pulsante per aggiungere altre occorrenze non coperte da RRULE
.
La proprietà EXDATE
è simile a RDATE, ma specifica le date o le date e le ore in cui l'evento non deve verificarsi. In altre parole, queste occorrenze devono
essere escluse. Deve puntare a un'istanza valida generata dalla regola di ricorrenza.
EXDATE
e RDATE
possono avere un fuso orario e devono essere date (non date-ore) per gli eventi che durano tutto il giorno.
Ogni proprietà può trovarsi più volte all'interno del campo della 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:
Un evento che si svolge dalle 6 alle 7 ogni martedì e venerdì a partire dal 15 settembre 2015 e termina dopo la quinta edizione 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" ], …
Un evento di una giornata che inizia il 1° giugno 2015 e si ripete ogni 3 giorni durante 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 particolari in momenti diversi. Queste istanze agiscono come eventi a loro volta.
Le modifiche di eventi ricorrenti possono interessare l'intero evento ricorrente (e tutte le sue istanze) o solo le singole istanze. Le istanze che differiscono dall'evento ricorrente principale sono chiamate eccezioni.
Ad esempio, un'eccezione potrebbe avere un riepilogo diverso, un'ora di inizio diversa o altri partecipanti invitati solo a quell'istanza. Puoi anche annullare completamente un'istanza senza rimuovere l'evento ricorrente (le cancellazioni dell'istanza si riflettono nell'evento status
).
Esempi di come utilizzare eventi e istanze ricorrenti tramite l'API Google Calendar sono disponibili qui.
Fusi orari
Un fuso orario specifica una regione che osserva un'ora standard uniforme. Nell'API Google Calendar, specifichi i fusi orari utilizzando identificatori del fuso orario IANA.
Puoi impostare il fuso orario sia per i calendari che 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 sui risultati delle query. Il fuso orario del calendario influisce sul modo in cui i valori temporali vengono interpretati o presentati dai metodi events.get()
, events.list()
e events.instances()
.
- Conversione nel fuso orario del risultato della query
- I risultati dei metodi
get()
,list()
einstances()
vengono restituiti nel fuso orario specificato nel parametrotimeZone
. Se ometti questo parametro, questi metodi utilizzeranno tutti il fuso orario del calendario come predefinito. - Abbinare gli eventi che durano tutto il giorno alle query con parentesi quadre
- I metodi
list()
einstances()
ti consentono di specificare i filtri relativi alle ore di inizio e di fine. Il metodo restituisce istanze che rientrano nell'intervallo specificato. Il fuso orario del calendario viene utilizzato per calcolare le ore di inizio e di fine degli eventi che durano tutto il giorno e determinare se rientrano nella specifica del filtro.
Fuso orario evento
Le istanze di eventi hanno un'ora di inizio e un'ora di fine; la specifica per questi orari può includere il fuso orario. Puoi specificare il fuso orario in diversi modi. Per i seguenti casi, l'ora viene specificata tutti nello stesso orario:
- Includi un offset di fuso orario nel campo
dateTime
, ad esempio2017-01-25T09:00:00-0500
. - Specifica l'ora senza offset, ad esempio
2017-01-25T09:00:00
, lasciando vuoto il campotimeZone
(questa operazione utilizza implicitamente il fuso orario predefinito). - Specifica l'ora senza offset, ad esempio
2017-01-25T09:00:00
, ma utilizza il campotimeZone
per specificare il fuso orario.
Se preferisci, puoi anche specificare gli orari degli eventi nel fuso orario UTC:
- Specifica l'ora nel fuso orario UTC:
2017-01-25T14:00:00Z
oppure utilizza uno scarto zero2017-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:
Fuso orario dell'evento ricorrente
Per gli eventi ricorrenti è necessario sempre specificare un unico fuso orario. È necessaria per espandere le occorrenze dell'evento.