Gibt Termine im angegebenen Kalender zurück. Jetzt testen oder Beispiel ansehen
Anfrage
HTTP-Anfrage
GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
Parameter
Parametername | Wert | Beschreibung |
---|---|---|
Pfadparameter | ||
calendarId |
string |
Kalender-ID. Rufen Sie die Methode calendarList.list auf, um Kalender-IDs abzurufen. Wenn Sie auf den primären Kalender des aktuell angemeldeten Nutzers zugreifen möchten, verwenden Sie das Keyword „primary “.
|
Optionale Suchparameter | ||
alwaysIncludeEmail |
boolean |
Verworfen und ignoriert. |
eventTypes |
string |
Die Ereignistypen, die zurückgegeben werden sollen. Optional. Dieser Parameter kann mehrmals wiederholt werden, um Ereignisse verschiedener Typen zurückzugeben. Wenn nicht festgelegt, werden alle Ereignistypen zurückgegeben.
Zulässige Werte sind:
|
iCalUID |
string |
Gibt eine Ereignis-ID im iCalendar-Format an, die in der Antwort enthalten sein muss. Optional. Verwenden Sie diese Option, wenn Sie nach einem Termin anhand seiner iCalendar-ID suchen möchten. |
maxAttendees |
integer |
Die maximale Anzahl der Teilnehmer, die in der Antwort enthalten sein sollen. Wenn die Anzahl der Teilnehmer über der angegebenen Anzahl liegt, wird nur der Teilnehmer zurückgegeben. Optional. |
maxResults |
integer |
Maximale Anzahl von Ereignissen, die auf einer Ergebnisseite zurückgegeben werden. Die Anzahl der Ereignisse auf der Ergebnisseite kann unter diesem Wert liegen oder es können gar keine Ereignisse vorhanden sein, auch wenn mehr Ereignisse mit der Abfrage übereinstimmen. Unvollständige Seiten können anhand eines nicht leeren nextPageToken -Felds in der Antwort erkannt werden. Der Standardwert ist 250 Ereignisse. Die Seitengröße darf maximal 2.500 Ereignisse umfassen. Optional.
|
orderBy |
string |
Die Reihenfolge der Ereignisse, die im Ergebnis zurückgegeben werden. Optional. Standardmäßig ist eine nicht spezifizierte, stabile Reihenfolge festgelegt.
Zulässige Werte sind:
|
pageToken |
string |
Token, das angibt, welche Ergebnisseite zurückgegeben werden soll. Optional. |
privateExtendedProperty |
string |
Einschränkung für erweiterte Eigenschaften, die als propertyName=value angegeben ist. Nur mit privaten Unterkünften übereinstimmen Dieser Parameter kann mehrmals wiederholt werden, um Ereignisse zurückzugeben, die allen angegebenen Einschränkungen entsprechen. |
q |
string |
Suchbegriffe für die kostenlose Textsuche, um Ereignisse zu finden, die mit diesen Begriffen in den folgenden Feldern übereinstimmen:
Außerdem werden mit diesen Suchbegriffen vordefinierte Keywords mit allen Übersetzungen des Anzeigenamens von Ereignissen für den Arbeitsort, Abwesenheit und Fokuszeit abgeglichen. Wenn Sie beispielsweise nach „Büro“ oder „Arbeitsplatz“ suchen, werden Ereignisse vom Typ |
sharedExtendedProperty |
string |
Einschränkung für erweiterte Eigenschaften, die als propertyName=value angegeben ist. Nur mit geteilten Unterkünften übereinstimmen Dieser Parameter kann mehrmals wiederholt werden, um Ereignisse zurückzugeben, die allen angegebenen Einschränkungen entsprechen. |
showDeleted |
boolean |
Gibt an, ob gelöschte Ereignisse (status = cancelled ) in das Ergebnis eingeschlossen werden sollen. Abgesagte Instanzen wiederkehrender Ereignisse (aber nicht das zugrunde liegende wiederkehrende Ereignis) werden weiterhin berücksichtigt, wenn showDeleted und singleEvents beides False sind. Wenn showDeleted und singleEvents beide „Wahr“ sind, werden nur einzelne Instanzen gelöschter Ereignisse zurückgegeben, aber nicht die zugrunde liegenden wiederkehrenden Ereignisse. Optional. Die Standardeinstellung ist "False".
|
showHiddenInvitations |
boolean |
Gibt an, ob ausgeblendete Einladungen in das Ergebnis einbezogen werden sollen. Optional. Die Standardeinstellung ist "False". |
singleEvents |
boolean |
Gibt an, ob wiederkehrende Ereignisse in Instanzen aufgeschlüsselt werden sollen und nur einzelne einmalige Ereignisse und Instanzen wiederkehrender Ereignisse zurückgegeben werden, nicht aber die zugrunde liegenden wiederkehrenden Ereignisse selbst. Optional. Die Standardeinstellung ist "False". |
syncToken |
string |
Token aus dem Feld nextSyncToken , das auf der letzten Ergebnisseite der vorherigen Listenanfrage zurückgegeben wurde. Dadurch enthält das Ergebnis dieser Listenanfrage nur Einträge, die sich seitdem geändert haben. Alle Ereignisse, die seit der vorherigen Listenanfrage gelöscht wurden, sind immer im Ergebnissatz enthalten. Außerdem darf showDeleted nicht auf „False“ gesetzt werden. Es gibt mehrere Abfrageparameter, die nicht zusammen mit nextSyncToken angegeben werden können, um für einen konsistenten Clientstatus zu sorgen. Das sind:
syncToken abläuft, antwortet der Server mit dem Antwortcode 410 GONE. Der Client sollte dann seinen Speicher leeren und eine vollständige Synchronisierung ohne syncToken ausführen. Weitere Informationen zur inkrementellen Synchronisierung Optional. Standardmäßig werden alle Einträge zurückgegeben. |
timeMax |
datetime |
Obergrenze (exklusiv) für den Beginn eines Ereignisses, nach dem gefiltert werden soll. Optional. Standardmäßig wird nicht nach Beginn gefiltert. Muss ein RFC3339-Zeitstempel mit obligatorischem Zeitzonenoffset sein, z. B. 2011-06-03T10:00:00-07:00 oder 2011-06-03T10:00:00Z. Millisekunden können angegeben werden, werden aber ignoriert. Wenn timeMin festgelegt ist, muss timeMax größer als timeMin sein.
|
timeMin |
datetime |
Untere Grenze (exklusiv) für die Endzeit eines Ereignisses, nach der gefiltert werden soll. Optional. Standardmäßig wird nicht nach Endzeit gefiltert. Muss ein RFC3339-Zeitstempel mit obligatorischem Zeitzonenoffset sein, z. B. 2011-06-03T10:00:00-07:00 oder 2011-06-03T10:00:00Z. Millisekunden können angegeben werden, werden aber ignoriert. Wenn timeMax festgelegt ist, muss timeMin kleiner als timeMax sein.
|
timeZone |
string |
Die in der Antwort verwendete Zeitzone. Optional. Standardmäßig ist die Zeitzone des Kalenders festgelegt. |
updatedMin |
datetime |
Untere Grenze für die Uhrzeit der letzten Änderung eines Ereignisses (als RFC3339-Zeitstempel), nach der gefiltert werden soll. Wenn Sie einen Wert angeben, werden Einträge, die danach gelöscht wurden, unabhängig von showDeleted immer berücksichtigt. Optional. Standardmäßig wird nicht nach der Uhrzeit der letzten Änderung gefiltert.
|
Autorisierung
Diese Anfrage ermöglicht die Autorisierung für mindestens einen der folgenden Zugriffsbereiche:
Umfang |
---|
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 |
Weitere Informationen finden Sie auf der Seite Authentifizierung und Autorisierung.
Anfragetext
Mit dieser Methode keinen Anfragetext bereitstellen.
Antwort
Bei Erfolg gibt diese Methode einen Antworttext mit der folgenden Struktur zurück:
{ "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 ] }
Name der Eigenschaft | Wert | Beschreibung | Hinweise |
---|---|---|---|
kind |
string |
Typ der Sammlung („calendar#events “). |
|
etag |
etag |
ETag der Sammlung. | |
summary |
string |
Titel des Kalenders. Schreibgeschützt. | |
description |
string |
Beschreibung des Kalenders. Schreibgeschützt. | |
updated |
datetime |
Die letzte Änderungszeit des Kalenders als RFC3339-Zeitstempel. Schreibgeschützt. | |
timeZone |
string |
Die Zeitzone des Kalenders. Schreibgeschützt. | |
accessRole |
string |
Die Zugriffsrolle des Nutzers für diesen Kalender. Schreibgeschützt. Mögliche Werte sind:
|
|
defaultReminders[] |
list |
Die Standarderinnerungen im Kalender des authentifizierten Nutzers. Diese Erinnerungen gelten für alle Termine in diesem Kalender, die nicht explizit überschrieben werden (d.h. für die reminders.useDefault nicht auf „Wahr“ gesetzt ist). |
|
defaultReminders[].method |
string |
Die von dieser Erinnerung verwendete Methode. Mögliche Werte sind:
Erforderlich, wenn Sie eine Erinnerung hinzufügen. |
Bearbeitbar |
defaultReminders[].minutes |
integer |
Anzahl der Minuten vor Beginn der Veranstaltung, zu der die Erinnerung ausgelöst werden soll. Gültige Werte liegen zwischen 0 und 40.320 (4 Wochen in Minuten). Erforderlich, wenn Sie eine Erinnerung hinzufügen. |
Bearbeitbar |
nextPageToken |
string |
Token, das für den Zugriff auf die nächste Seite dieses Ergebnisses verwendet wird. Wird weggelassen, wenn keine weiteren Ergebnisse verfügbar sind. In diesem Fall wird nextSyncToken angegeben. |
|
items[] |
list |
Liste der Termine im Kalender. | |
nextSyncToken |
string |
Token, das zu einem späteren Zeitpunkt verwendet wird, um nur die Einträge abzurufen, die sich seit der Rückgabe dieses Ergebnisses geändert haben. Wird weggelassen, wenn weitere Ergebnisse verfügbar sind. In diesem Fall wird nextPageToken angegeben. |
Beispiele
Hinweis: Bei den für diese Methode verfügbaren Codebeispielen sind nicht alle unterstützten Programmiersprachen vertreten. Eine Liste der unterstützten Sprachen finden Sie auf der Seite für Clientbibliotheken.
Java
Verwendet die Java-Clientbibliothek.
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
Verwendet die Python-Clientbibliothek.
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
Verwendet die PHP-Clientbibliothek.
$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
Verwendet die Ruby-Clientbibliothek.
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?
Testen!
Verwenden Sie den unten angegebenen APIs Explorer, um diese Methode für Livedaten aufzurufen und die Antwort einzusehen.