Events: list

Nota: l'autorizzazione è facoltativa.

Restituisce gli eventi nel calendario specificato. Prova ora o guarda un esempio.

Richiesta

Richiesta HTTP

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

Parametri

Nome del 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 che ha eseguito l'accesso, utilizza la parola chiave "primary".
Parametri di query facoltativi
alwaysIncludeEmail	boolean	Ritirata e ignorata.
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 con una ricorrenza annuale. "default": eventi regolari. "focusTime": eventi di momento di concentrazione. "fromGmail": eventi da Gmail. "outOfOffice": eventi fuori sede. "workingLocation": eventi relativi alla sede di lavoro.
iCalUID	string	Specifica un ID evento nel formato iCalendar da fornire nella risposta. Facoltativo. Utilizzalo 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 non essere presente alcun evento, anche se sono presenti più eventi corrispondenti 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 essere superiori a 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 (crescente). Questa opzione è disponibile solo quando esegui query su singoli eventi (ovvero quando il parametro singleEvents è True) "updated": ordina per data/ora ultima modifica (in ordine crescente).
pageToken	string	Token che specifica la pagina di risultati da restituire. Facoltativo.
privateExtendedProperty	string	Vincolo delle proprietà estese specificato come propertyName=value. Corrisponde solo alle proprietà private. Questo parametro può essere ripetuto più volte per restituire gli eventi corrispondenti a tutti i vincoli specificati.
q	string	Termini di ricerca di testo libero per trovare gli eventi corrispondenti 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 alle parole chiave predefinite per tutte le traduzioni dei titoli visualizzati degli eventi relativi a posizione di lavoro, fuori sede e ora di concentrazione. Ad esempio, la ricerca di "Ufficio" o "Bureau" restituisce eventi relativi alla sede di lavoro di tipo officeLocation, mentre la ricerca di "Fuori sede" o "Abwesend" restituisce eventi di assenza. Facoltativo.
sharedExtendedProperty	string	Vincolo delle proprietà estese specificato come propertyName=value. Corrisponde solo alle proprietà condivise. Questo parametro può essere ripetuto più volte per restituire gli eventi corrispondenti a tutti i vincoli specificati.
showDeleted	boolean	Indica se includere o meno nel risultato gli eventi eliminati (con status uguale a "cancelled"). 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 singoli eventi una tantum 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 richiesta dell'elenco precedente. Il risultato di questa richiesta dell'elenco contiene solo le voci che sono cambiate da allora. Tutti gli eventi eliminati dalla richiesta di elenco precedente saranno sempre nel set di risultati e non è consentito impostare showDeleted su False. Esistono diversi parametri di query che non possono essere specificati insieme a nextSyncToken per garantire la coerenza dello stato del client. ovvero: iCalUID orderBy privateExtendedProperty q sharedExtendedProperty timeMin timeMax updatedMin Tutti gli altri parametri di query devono essere gli stessi utilizzati per la sincronizzazione iniziale per evitare comportamenti non definiti. Se syncToken scade, il server risponderà con un codice di risposta 410 GONE e il client dovrà svuotare lo spazio di archiviazione ed eseguire una sincronizzazione completa senza syncToken. Scopri di più sulla sincronizzazione incrementale. Facoltativo. L'impostazione predefinita è restituire tutte le voci.
timeMax	datetime	Soglia superiore (esclusa) per l'ora di inizio di un evento in base alla quale filtrare. Facoltativo. L'impostazione predefinita è non filtrare per ora di inizio. Deve essere un timestamp RFC3339 con offset di 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 al quale applicare il filtro. Facoltativo. Per impostazione predefinita, non viene applicato alcun filtro in base all'ora di fine. Deve essere un timestamp RFC3339 con offset di 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 è impostato timeMax, timeMin deve essere inferiore a timeMax.
timeZone	string	Fuso orario utilizzato nella risposta. Facoltativo. Il valore predefinito è il fuso orario del calendario.
updatedMin	datetime	Limite inferiore per l'ora dell'ultima modifica di un evento (come timestamp RFC3339) in base al quale applicare il filtro. Se specificato, le voci eliminate da questo momento in poi verranno sempre incluse, indipendentemente da showDeleted. Facoltativo. Per impostazione predefinita, non viene applicato alcun filtro 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 specificare 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	Titolo del calendario. Sola lettura.
description	string	Descrizione del calendario. Sola lettura.
updated	datetime	Data e ora dell'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 su stato libero/occupato. "reader": l'utente ha accesso in lettura al calendario. Gli eventi privati verranno visualizzati agli utenti con accesso in qualità di lettore, ma i dettagli degli eventi verranno nascosti. "writer": l'utente ha accesso in lettura e scrittura al calendario. Gli eventi privati verranno visualizzati agli utenti con accesso come autore e i relativi dettagli saranno visibili. "owner": l'utente è il proprietario del calendario. Questo ruolo ha tutte le autorizzazioni del ruolo Scrittore, con la possibilità aggiuntiva di visualizzare e manipolare le ACL.
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 sostituiscono esplicitamente (ovvero per i quali reminders.useDefault non è 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 aggiungi 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 aggiungi 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 di eventi nel calendario.
nextSyncToken	string	Token utilizzato in un secondo momento per recuperare solo le voci che sono cambiate da quando è stato restituito questo risultato. Omesso se sono disponibili altri risultati, nel qual caso viene fornito nextPageToken.

Esempi

Nota: gli esempi di codice disponibili per questo metodo non rappresentano tutti i linguaggi di programmazione supportati (consulta la pagina relativa alle librerie client per un elenco dei linguaggi supportati).

Java

Utilizza la libreria client Java.

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;
import com.google.api.services.calendar.model.Events;

// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Iterate over the events in the specified calendar
String pageToken = null;
do {
  Events events = service.events().list('primary').setPageToken(pageToken).execute();
  List<Event> items = events.getItems();
  for (Event event : items) {
    System.out.println(event.getSummary());
  }
  pageToken = events.getNextPageToken();
} while (pageToken != null);

Python

Utilizza la libreria client Python.

page_token = None
while True:
  events = service.events().list(calendarId='primary', pageToken=page_token).execute()
  for event in events['items']:
    print event['summary']
  page_token = events.get('nextPageToken')
  if not page_token:
    break

PHP

Utilizza la libreria client PHP.

$events = $service->events->listEvents('primary');

while(true) {
  foreach ($events->getItems() as $event) {
    echo $event->getSummary();
  }
  $pageToken = $events->getNextPageToken();
  if ($pageToken) {
    $optParams = array('pageToken' => $pageToken);
    $events = $service->events->listEvents('primary', $optParams);
  } else {
    break;
  }
}

Ruby

Utilizza la libreria client Ruby.

page_token = nil
begin
  result = client.list_events('primary', page_token: page_token)
  result.items.each do |e|
    print e.summary + "\n"
  end
  if result.next_page_token != page_token
    page_token = result.next_page_token
  else
    page_token = nil
  end
end while !page_token.nil?

Prova

Utilizza l'Explorer API di seguito per chiamare questo metodo sui dati in tempo reale e visualizzare la risposta.