Questa pagina è stata tradotta dall'API Cloud Translation.

Calendari ed eventi

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

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 una data o a un intervallo di tempo 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, luogo, stato, promemoria, allegati e così via.

Tipi di eventi

Google Calendar supporta gli eventi singoli e ricorrenti:

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

Gli eventi possono anche essere con data e ora o giornalieri:

Un evento a tempo si verifica tra due momenti specifici. Gli eventi a tempo utilizzano i campi start.dateTime e end.dateTime per specificare quando si verificano.
Un evento giornaliero dura un'intera giornata o una serie consecutiva di giorni. Gli eventi tutte le mattine utilizzano i campi start.date e end.date per specificare quando si verificano. Tieni presente che il campo fuso orario non ha significato per gli eventi che durano tutto il giorno.

L'inizio e la fine dell'evento devono essere entrambi con data e ora o entrambi per l'intera giornata. Ad esempio, non è valido specificare start.date e end.dateTime.

Organizzatori

Gli eventi hanno un unico organizzatore, ovvero il calendario contenente la copia principale dell'evento. Gli eventi possono anche avere più partecipanti. 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 relativo calendario principale non può mai essere eliminato o "annullato" dall'utente. Tuttavia, può essere comunque condiviso con altri utenti.

Oltre al calendario principale, puoi creare esplicitamente un numero illimitato di altri calendari, che possono essere modificati, eliminati e condivisi tra più utenti.

Calendario ed elenco di calendari

La raccolta Calendari rappresenta tutti i calendari esistenti. Può essere utilizzato per creare ed eliminare i calendari. Puoi anche recuperare o impostare 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 del calendario che un utente ha aggiunto al proprio elenco (mostrato nel riquadro a sinistra dell'interfaccia utente web). Puoi utilizzarlo per aggiungere e rimuovere i calendari esistenti dall'elenco degli utenti. Inoltre, lo utilizzi 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 seguente tabella 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 anche aggiunto all'elenco di calendari del creator.	Inserisce un calendario esistente nell'elenco dell'utente.
`delete`	Consente di eliminare un calendario secondario.	Rimuove un calendario dall'elenco dell'utente.
`get`	Recupera i metadati del calendario, ad esempio titolo e fuso orario.	Recupera i metadati oltre alle 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 verificano più volte in base a una pianificazione regolare, ad esempio riunioni settimanali, compleanni e festività. A parte l'ora di inizio e di fine diversa, spesso questi eventi ripetuti sono identici.

Gli eventi sono definiti ricorrenti se si ripetono in base a 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 di fine (che definiscono la prima occorrenza, come se si trattasse di un singolo evento autonomo) e
Il campo di ricorrenza (che definisce la frequenza con cui l'evento deve essere ripetuto nel tempo).

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

La proprietà RRULE è la più importante in quanto definisce una regola regolare per ripetere l'evento. È composto da diversi componenti. Ecco alcuni di questi:

FREQ: la frequenza con cui l'evento deve essere ripetuto (ad es.DAILY o WEEKLY). Obbligatorio.
INTERVAL: funziona insieme a FREQ per specificare la frequenza con cui deve essere ripetuto l'evento. Ad esempio, FREQ=DAILY;INTERVAL=2 significa una volta ogni due giorni.
COUNT: il numero di volte in cui l'evento deve essere ripetuto.

Puoi utilizzare COUNT o UNTIL per specificare la fine della ripetizione dell'evento. Non utilizzare entrambi nella stessa regola.
UNTIL: la data o la data e l'ora fino a cui 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 date e ora aggiuntive in cui devono verificarsi le occorrenze dell'evento. Ad esempio, RDATE;VALUE=DATE:19970101,19970120. Utilizzalo per aggiungere occorrenze aggiuntive 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 ripetizione.

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

Ciascuna delle proprietà può verificarsi più volte all'interno del campo di ripetizione. 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 verifica dalle 06:00 alle 07: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"
],
…

Un evento che dura tutto il giorno a partire dal 1° giugno 2015 e 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 più istanze: le sue particolari occorrenze in momenti diversi. Queste istanze fungono da eventi.

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 sono chiamate eccezioni.

Ad esempio, un'eccezione potrebbe avere un riepilogo diverso, un'ora di inizio diversa o partecipanti aggiuntivi invitati solo a quella specifica istanza. Puoi anche annullare completamente un'istanza senza rimuovere l'evento ricorrente (gli annullamenti delle istanze vengono riportati nell'evento status).

Qui puoi trovare esempi di come utilizzare eventi e istanze ricorrenti tramite l'API Google Calendar.

Fusi orari

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

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

Fuso orario del calendario

Il fuso orario del calendario è noto anche come fuso orario predefinito per le 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 del fuso orario dei risultati della query: I risultati dei metodi get(), list() e instances() vengono restituiti nel fuso orario specificato nel parametro timeZone. Se ometti questo parametro, tutti questi metodi utilizzano il fusorario del calendario come impostazione predefinita.
Corrispondenza di eventi per tutto il giorno a query con intervalli di tempo: I metodi list() e instances() ti consentono di specificare i filtri di inizio e fine, con il metodo che restituisce le 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 al fine di determinare se rientrano nella specifica del filtro.

Fuso orario evento

Le istanze di evento hanno un'ora di inizio e di fine; la specifica di queste ore potrebbe includere il fuso orario. Puoi specificare il fuso orario in diversi modi. I seguenti valori 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 una differenza di 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, come quando imposti un fuso orario dell'evento utilizzando l'interfaccia utente di Calendar:

Fuso orario dell'evento ricorrente

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