Events: list

Restituisce gli eventi nel calendario specificato. Prova subito.

Richiesta

Richiesta HTTP

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events

Parametri

Nome parametro Valore Descrizione
Parametri del percorso
calendarId string Identificatore del calendario. Per recuperare gli ID calendario, chiama il metodo calendarList.list. Se vuoi accedere al calendario principale dell'utente attualmente connesso, utilizza la parola chiave "primary".
Parametri di query facoltativi
alwaysIncludeEmail boolean Deprecato e ignorato.
eventTypes string Tipi di eventi da restituire. Facoltativo. Questo parametro può essere ripetuto più volte per restituire eventi di tipi diversi. Se non impostato, restituisce tutti i tipi di eventi.

I valori accettati sono:
  • "birthday": eventi speciali che durano tutto il giorno e si ripetono ogni anno.
  • "default": eventi regolari.
  • "focusTime": eventi di momento di concentrazione.
  • "fromGmail": Eventi da Gmail.
  • "outOfOffice": eventi fuori sede.
  • "workingLocation": eventi relativi al luogo di lavoro.
iCalUID string Specifica un ID evento in formato iCalendar da fornire nella risposta. Facoltativo. Utilizza questo campo se vuoi cercare un evento in base al relativo ID iCalendar.
maxAttendees integer Il numero massimo di partecipanti da includere nella risposta. Se il numero di partecipanti è superiore a quello specificato, viene restituito solo il partecipante. Facoltativo.
maxResults integer Numero massimo di eventi restituiti in una pagina dei risultati. Il numero di eventi nella pagina risultante potrebbe essere inferiore a questo valore o pari a zero, anche se ci sono più eventi che corrispondono alla query. Le pagine incomplete possono essere rilevate da un campo nextPageToken non vuoto nella risposta. Per impostazione predefinita, il valore è 250 eventi. Le dimensioni della pagina non possono mai superare i 2500 eventi. Facoltativo.
orderBy string L'ordine degli eventi restituiti nel risultato. Facoltativo. Il valore predefinito è un ordine stabile non specificato.

I valori accettati sono:
  • "startTime": ordina per data/ora di inizio (ordine crescente). Questa opzione è disponibile solo quando vengono eseguite query su singoli eventi (ovvero il parametro singleEvents è True)
  • "updated": ordina in base all'ora dell'ultima modifica (ordine crescente).
pageToken string Token che specifica quale pagina dei risultati restituire. Facoltativo.
privateExtendedProperty string Vincolo delle proprietà estese specificato come propertyName=value. Corrisponde solo alle proprietà private. Questo parametro potrebbe essere ripetuto più volte per restituire eventi che corrispondono a tutti i vincoli specificati.
q string Termini di ricerca di testo libero per trovare eventi che corrispondono a questi termini nei seguenti campi:
  • summary
  • description
  • location
  • displayName del partecipante
  • email del partecipante
  • displayName dell'organizzatore
  • email dell'organizzatore
  • workingLocationProperties.officeLocation.buildingId
  • workingLocationProperties.officeLocation.deskId
  • workingLocationProperties.officeLocation.label
  • workingLocationProperties.customLocation.label

Questi termini di ricerca corrispondono anche a parole chiave predefinite rispetto a tutte le traduzioni del titolo visualizzato di eventi di sede di lavoro, fuori sede e tempo di concentrazione. Ad esempio, la ricerca di "Ufficio" o "Bureau" restituisce eventi di tipo officeLocation relativi alla sede di lavoro, mentre la ricerca di "Fuori sede" o "Abwesend" restituisce eventi di assenza dall'ufficio. Facoltativo.
sharedExtendedProperty string Vincolo delle proprietà estese specificato come propertyName=value. Corrisponde solo alle proprietà condivise. Questo parametro potrebbe essere ripetuto più volte per restituire eventi che corrispondono a tutti i vincoli specificati.
showDeleted boolean Se includere o meno gli eventi eliminati (con status uguale a "cancelled") nel risultato. Le istanze annullate di eventi ricorrenti (ma non l'evento ricorrente sottostante) verranno comunque incluse se showDeleted e singleEvents sono entrambi False. Se showDeleted e singleEvents sono entrambi True, vengono restituite solo le singole istanze degli eventi eliminati (ma non gli eventi ricorrenti sottostanti). Facoltativo. Il valore predefinito è False.
showHiddenInvitations boolean Indica se includere gli inviti nascosti nel risultato. Facoltativo. Il valore predefinito è False.
singleEvents boolean Indica se espandere gli eventi ricorrenti in istanze e restituire solo eventi singoli e istanze di eventi ricorrenti, ma non gli eventi ricorrenti sottostanti. Facoltativo. Il valore predefinito è False.
syncToken string Token ottenuto dal campo nextSyncToken restituito nell'ultima pagina dei risultati della precedente richiesta di elenco. In questo modo, il risultato di questa richiesta di elenco contiene solo le voci modificate da allora. Tutti gli eventi eliminati dall'ultima richiesta di elenco saranno sempre inclusi nel set di risultati e non è consentito impostare showDeleted su False.
Per garantire la coerenza dello stato del client, non è possibile specificare diversi parametri di query insieme a nextSyncToken.

Questi sono:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
Tutti gli altri parametri di query devono essere uguali a quelli della sincronizzazione iniziale per evitare comportamenti indefiniti. Se syncToken scade, il server risponde con un codice di risposta 410 GONE e il client deve cancellare lo spazio di archiviazione ed eseguire una sincronizzazione completa senza syncToken.
Scopri di più sulla sincronizzazione incrementale.
(Facoltativo) Il valore predefinito è restituire tutte le voci.
timeMax datetime Limite superiore (esclusivo) per l'ora di inizio di un evento in base a cui filtrare. Facoltativo. Per impostazione predefinita, non viene applicato alcun filtro in base all'ora di inizio. Deve essere un timestamp RFC3339 con offset del fuso orario obbligatorio, ad esempio 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. I millisecondi possono essere forniti, ma vengono ignorati. Se timeMin è impostato, timeMax deve essere maggiore di timeMin.
timeMin datetime Limite inferiore (esclusivo) per l'ora di fine di un evento in base a cui filtrare. Facoltativo. L'impostazione predefinita non prevede il filtro in base all'ora di fine. Deve essere un timestamp RFC3339 con offset del fuso orario obbligatorio, ad esempio 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. I millisecondi possono essere forniti, ma vengono ignorati. Se timeMax è impostato, timeMin deve essere inferiore a timeMax.
timeZone string Il fuso orario utilizzato nella risposta. Facoltativo. Il valore predefinito è il fuso orario del calendario.
updatedMin datetime Limite inferiore dell'ora dell'ultima modifica di un evento (come timestamp RFC3339) in base al quale filtrare. Se specificato, le voci eliminate dopo questo orario verranno sempre incluse indipendentemente da showDeleted. Facoltativo. Per impostazione predefinita, il filtro non viene applicato in base all'ora dell'ultima modifica.

Autorizzazione

Questa richiesta consente l'autorizzazione con almeno uno dei seguenti ambiti:

Ambito
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.app.created
https://www.googleapis.com/auth/calendar.events.freebusy
https://www.googleapis.com/auth/calendar.events.owned
https://www.googleapis.com/auth/calendar.events.owned.readonly
https://www.googleapis.com/auth/calendar.events.public.readonly

Per ulteriori informazioni, consulta la pagina Autenticazione e autorizzazione.

Corpo della richiesta

Non fornire un corpo della richiesta con questo metodo.

Risposta

In caso di esito positivo, questo metodo restituisce un corpo della risposta con la seguente struttura:

{
  "kind": "calendar#events",
  "etag": etag,
  "summary": string,
  "description": string,
  "updated": datetime,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      "method": string,
      "minutes": integer
    }
  ],
  "nextPageToken": string,
  "nextSyncToken": string,
  "items": [
    events Resource
  ]
}
Nome proprietà Valore Descrizione Note
kind string Tipo di raccolta ("calendar#events").
etag etag ETag della raccolta.
summary string Il titolo del calendario. Sola lettura.
description string Descrizione del calendario. Sola lettura.
updated datetime Data/ora ultima modifica del calendario (come timestamp RFC3339). Sola lettura.
timeZone string Il fuso orario del calendario. Sola lettura.
accessRole string Il ruolo di accesso dell'utente per questo calendario. Sola lettura. I valori possibili sono:
  • "none": l'utente non ha accesso.
  • "freeBusyReader": l'utente ha accesso in lettura alle informazioni sul servizio libero/occupato.
  • "reader": l'utente ha accesso in lettura al calendario. Gli eventi privati verranno visualizzati dagli utenti con accesso in lettura, ma i dettagli degli eventi verranno nascosti.
  • "writer": l'utente ha accesso in lettura e scrittura al calendario. Gli eventi privati verranno visualizzati dagli utenti con accesso di scrittura e i dettagli dell'evento saranno visibili.
  • "owner": l'utente dispone dell'accesso amministratore al calendario. Questo ruolo dispone di tutte le autorizzazioni del ruolo Autore, con la possibilità aggiuntiva di visualizzare e modificare i livelli di accesso di altri utenti.

defaultReminders[] list I promemoria predefiniti nel calendario per l'utente autenticato. Questi promemoria si applicano a tutti gli eventi di questo calendario che non li ignorano esplicitamente (ovvero non hanno reminders.useDefault impostato su True).
defaultReminders[].method string Il metodo utilizzato da questo promemoria. I valori possibili sono:
  • "email": i promemoria vengono inviati via email.
  • "popup": i promemoria vengono inviati tramite un popup dell'interfaccia utente.

Obbligatorio quando si aggiunge un promemoria.

 scrivibile
defaultReminders[].minutes integer Numero di minuti prima dell'inizio dell'evento in cui deve essere attivato il promemoria. I valori validi sono compresi tra 0 e 40320 (4 settimane in minuti).

Obbligatorio quando si aggiunge un promemoria.

 scrivibile
nextPageToken string Token utilizzato per accedere alla pagina successiva di questo risultato. Omesso se non sono disponibili altri risultati, nel qual caso viene fornito nextSyncToken.
items[] list Elenco degli eventi nel calendario.
nextSyncToken string Token utilizzato in un secondo momento per recuperare solo le voci modificate da quando è stato restituito questo risultato. Omesso se sono disponibili altri risultati, nel qual caso viene fornito nextPageToken.

Prova

Utilizza Explorer API di seguito per chiamare questo metodo sui dati live e visualizzare la risposta.