Questa pagina è stata tradotta dall'API Cloud Translation.

Calendari ed eventi

Questa guida descrive i calendari, gli eventi e le loro relazioni.

Calendari

Un calendario è una raccolta di eventi correlati, insieme a metadati aggiuntivi come riepilogo, fuso orario predefinito, località ecc. Ogni calendario viene 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 all'inizio data e ora di fine, gli eventi contengono altri dati, come riepilogo, descrizione luogo, stato, promemoria, allegati ecc.

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 a tempo o tutto il giorno:

Un evento a tempo si verifica tra due momenti specifici. Eventi a tempo usa i campi start.dateTime e end.dateTime per specificare quando che si verificano.
Un evento che dura tutto il giorno dura un'intera giornata o serie consecutive di giorni. Tutto il giorno usano 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.

L'inizio e la fine dell'evento devono essere entrambi sincronizzati o entrambi per tutto il giorno. Ad esempio, non è valido specificare start.date e end.dateTime.

Organizzatori

Gli eventi hanno un singolo organizzatore, ovvero il calendario che contiene la copia principale dell'evento. Gli eventi possono anche avere più partecipanti. Il partecipante corrisponde in genere al 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

Il calendario principale è un tipo speciale di calendario associato a un solo calendario: account utente. Questo calendario viene creato automaticamente per ogni nuovo account utente e solitamente l'ID corrisponde all'indirizzo email principale dell'utente. Purché esiste già un account, il relativo calendario principale non può mai essere eliminato o non è di sua proprietà dal utente. Tuttavia, potrà essere condiviso con altri utenti.

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

Calendario e elenco di calendari

La raccolta Calendari rappresenta tutti i calendari esistenti. Può essere usato per creare ed eliminare calendari. Puoi anche recuperare o impostare proprietà globali utenti con accesso a un calendario. Ad esempio, il titolo e il valore predefinito di un calendario sono proprietà globali.

CalendarList è un raccolta di tutte le voci di calendario che un utente ha aggiunto al proprio elenco (mostrate nel riquadro sinistro della UI web). Puoi utilizzarla per aggiungere e rimuovere calendari da/verso l'elenco degli utenti. Puoi utilizzarlo anche per recuperare e impostare valori di proprietà di calendario specifiche per l'utente, come i promemoria predefiniti. Un altro ad esempio il colore in primo piano, dato che utenti diversi possono avere colori diversi. impostati per lo stesso calendario.

Nella tabella seguente viene confrontato il significato delle operazioni per le due raccolte:

Operazione	Calendari	CalendarList
`insert`	Crea un nuovo calendario secondario. Per impostazione predefinita, questo calendario aggiunto all'elenco dei calendari dell'autore.	Inserisce un calendario esistente nell'elenco degli utenti.
`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 e la personalizzazione specifica dell'utente come colorare i promemoria o eseguirne l'override.
`patch`/`update`	Modifica i metadati del calendario.	Modifica le proprietà dei calendari specifiche dell'utente.

Eventi ricorrenti

Alcuni eventi si verificano più volte secondo una pianificazione regolare, ad esempio riunioni settimanali, compleanni e festività. A parte avere ore di inizio e di fine diverse, questi eventi ripetuti sono spesso identici.

Gli eventi sono chiamati 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 relativi campi di inizio e fine (che definiscono la prima occorrenza, come se fosse un singolo evento autonomo) e
Il relativo campo di ricorrenza (che definisce il modo in cui l'evento deve essere ripetuto nel tempo).

Il campo della 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. È 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: collabora con FREQ per specificare la frequenza dell'evento deve essere ripetuto. Ad esempio, FREQ=DAILY;INTERVAL=2 significa che una volta ogni due giorni.
COUNT: numero di volte in cui questo evento deve essere ripetuto.

Puoi utilizzare COUNT o UNTIL per specificare la fine della ricorrenza degli eventi. Non utilizzarli entrambi nella stessa regola.
UNTIL: la data o la data e l'ora fino alla quale l'evento deve essere ripetuto (inclusa).
BYDAY: giorni della settimana in cui l'evento deve essere ripetuto (SU, MO, TU e così via). Altri componenti simili sono BYMONTH, BYYEARDAY e BYHOUR.

La proprietà RDATE specifica date o ore aggiuntive in cui l'evento ogni occorrenza. Ad esempio, RDATE;VALUE=DATE:19970101,19970120. Utilizzalo per aggiungere altre occorrenze non coperte dall'RRULE.

La proprietà EXDATE è simile a RDATE, ma specifica date o date-ore in cui l'evento non dovrebbe verificarsi. Vale a dire che tali occorrenze 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-ora) per gli eventi che durano tutto il giorno.

Ciascuna 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 la Quelle escluse da tutte le EXDATE regole.

Ecco alcuni esempi di eventi ricorrenti:

Un evento che si svolge dalle 6:00 alle 7:00 ogni martedì e venerdì a partire dalle 06:00-07:00 dal 15 settembre 2015 e con sosta dopo la quinta occorrenza prevista 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 dal 1° giugno 2015 e si ripete ogni 3 giorni tutto il mese, escluso il 10 giugno e il 9 e l'11 giugno inclusi:

...
"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 e eccezioni

Un evento ricorrente è costituito da diverse istanze: le sue occorrenze particolari in momenti diversi. Queste istanze agiscono come eventi stessi.

Le modifiche ricorrenti di un evento possono interessare l'intero un evento ricorrente (e tutte le sue istanze) o soltanto singole istanze. Le istanze che differiscono dall'evento ricorrente principale sono chiamate eccezioni.

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

Esempi di come lavorare con eventi e istanze ricorrenti tramite L'API Google Calendar è disponibile qui.

Fusi orari

Un fuso orario specifica una regione che osserva un orario standard uniforme. Nell'API Google Calendar, puoi specificare i fusi orari utilizzando Identificatori del fuso orario IANA.

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

Fuso orario del calendario

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

Conversione del fuso orario del risultato della query: Risultati delle get() list() e instances() vengono restituiti nel fuso orario specificato nella timeZone . Se ometti questo parametro, tutti questi metodi utilizzano il calendario fuso orario predefinito.
Associare gli eventi che durano tutto il giorno alle query con intervallo temporale: Il list() e instances() consentono di specificare i filtri di inizio e fine, con il metodo 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 evento

Le istanze di evento hanno un'ora di inizio e di fine. la specifica per questi orari potrebbe includere il fuso orario. Puoi specificare il fuso orario in diversi modi. il tutti i seguenti hanno lo stesso orario:

Includi uno scarto di fuso orario nel campo dateTime, ad esempio 2017-01-25T09:00:00-0500.
Specifica l'ora senza scarto, ad esempio 2017-01-25T09:00:00, lasciando vuoto il campo timeZone (utilizza implicitamente il fuso orario predefinito).
Specifica l'ora senza scarto, ad esempio 2017-01-25T09:00:00, ma utilizza il campo timeZone per specificare il fuso orario.

Puoi anche specificare gli orari degli eventi nel fuso orario UTC, se preferisci:

Specifica l'ora nel formato UTC: 2017-01-25T14:00:00Z oppure utilizza uno scarto pari a zero 2017-01-25T14:00:00+0000.

La rappresentazione interna dell'ora dell'evento è la stessa in tutti questi casi, ma impostando il campo timeZone viene aggiunto un fuso orario all'evento, proprio come quando imposti il fuso orario di un evento utilizzando l'app Calendario Interfaccia utente:

Fuso orario evento ricorrente

Per gli eventi ricorrenti, è necessario specificare sempre un unico fuso orario. È necessario per espandere le ricorrenze dell'evento.