Events: list

Zwraca wydarzenia z określonego kalendarza. Wypróbuj teraz lub zobacz przykład.

Prośba

Żądanie HTTP

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

Parametry

Nazwa parametru Wartość Opis
Parametry ścieżki
calendarId string Identyfikator kalendarza. Aby pobrać identyfikatory kalendarzy, wywołaj metodę calendarList.list. Jeśli chcesz uzyskać dostęp do kalendarza głównego aktualnie zalogowanego użytkownika, użyj słowa kluczowego „primary”.
Opcjonalne parametry zapytania
alwaysIncludeEmail boolean Wycofane i zignorowane. W przypadku organizatora, twórcy i uczestników zawsze zwracana będzie wartość w polu email, nawet jeśli rzeczywisty adres e-mail jest niedostępny (tzn. zostanie udostępniony wygenerowany, niedziałający adres).
eventTypes string Typy zdarzeń do zwrócenia. Opcjonalnie. Możliwe wartości:
  • "default"
  • "focusTime"
  • "outOfOffice"
  • "workingLocation"
Ten parametr można powtarzać wiele razy, aby zwrócić zdarzenia różnych typów. Wartość domyślna to ["default", "focusTime", "outOfOffice"].
iCalUID string Określa identyfikator wydarzenia w formacie iCalendar, który ma być podawany w odpowiedzi. Opcjonalnie. Użyj tej opcji, jeśli chcesz wyszukać wydarzenie według jego identyfikatora iCalendar.
maxAttendees integer Maksymalna liczba uczestników, których można uwzględnić w odpowiedzi. Jeśli uczestników jest więcej niż określona liczba, zwracany jest tylko uczestnik. Opcjonalnie.
maxResults integer Maksymalna liczba zdarzeń zwróconych na jednej stronie wyników. Liczba zdarzeń na stronie wynikowej może być mniejsza od tej wartości lub nie zawierać ich wcale, nawet jeśli jest więcej zdarzeń pasujących do zapytania. Strony niekompletne można wykryć po niepustym polu nextPageToken w odpowiedzi. Domyślnie wartością jest 250 zdarzeń. Rozmiar strony nigdy nie może przekraczać 2500 zdarzeń. Opcjonalnie.
orderBy string Kolejność zdarzeń zwróconych w wyniku. Opcjonalnie. Domyślną wartością jest nieokreślona, stabilna kolejność.

Akceptowane wartości:
  • „startTime”: sortuj według daty/godziny rozpoczęcia (rosnąco). Ta funkcja jest dostępna tylko w przypadku wysyłania zapytań dotyczących pojedynczych zdarzeń (np.parametr singleEvents ma wartość Prawda).
  • „updated”: sortuj według czasu ostatniej modyfikacji (rosnąco).
pageToken string Token określający stronę wyników do zwrócenia. Opcjonalnie.
privateExtendedProperty string Ograniczenie właściwości rozszerzonych określone jako propertyName=value. Pasuje tylko do usług prywatnych. Ten parametr może być powtarzany wiele razy, aby zwrócić zdarzenia pasujące do wszystkich podanych ograniczeń.
q string Wyszukiwane hasła, które można wyszukać w następujących polach:
  • summary
  • description
  • location
  • displayName uczestnika
  • email uczestnika
  • workingLocationProperties.officeLocation.buildingId
  • workingLocationProperties.officeLocation.deskId
  • workingLocationProperties.officeLocation.label
  • workingLocationProperties.customLocation.label

Te wyszukiwane hasła pasują też do wstępnie zdefiniowanych słów kluczowych do wszystkich wyświetlanych tytułów miejsc pracy, poza biurem i czasu skupienia. Na przykład wyszukiwanie „Biuro” lub „Biuro” zwróci zdarzenia związane z lokalizacją miejsca pracy typu officeLocation, a wyszukiwanie „Poza biurem” lub „Abwesend” zwróci wydarzenia „poza biurem”. Opcjonalnie.
sharedExtendedProperty string Ograniczenie właściwości rozszerzonych określone jako propertyName=value. Pasuje tylko do udostępnionych usług. Ten parametr może być powtarzany wiele razy, aby zwrócić zdarzenia pasujące do wszystkich podanych ograniczeń.
showDeleted boolean Określa, czy w wyniku mają zostać uwzględnione usunięte zdarzenia (z status równa się „cancelled”). Anulowane wystąpienia wydarzeń cyklicznych (ale nie powiązane z nimi wydarzenia cykliczne) będą nadal uwzględniane, jeśli oba zdarzenia showDeleted i singleEvents mają wartość Fałsz. Jeśli showDeleted i singleEvents mają wartość Prawda, zwracane są tylko pojedyncze wystąpienia usuniętych wydarzeń (ale nie powiązane z nimi wydarzenia cykliczne). Opcjonalnie. Wartość domyślna to False (Fałsz).
showHiddenInvitations boolean Określa, czy w wyniku mają być uwzględniane ukryte zaproszenia. Opcjonalnie. Wartość domyślna to False (Fałsz).
singleEvents boolean Określa, czy rozwinąć wydarzenia cykliczne do wystąpień i zwrócić tylko jednorazowe wydarzenia i ich wystąpienia, ale nie same wydarzenia cykliczne. Opcjonalnie. Wartość domyślna to False (Fałsz).
syncToken string Token uzyskany z pola nextSyncToken zwróconego na ostatniej stronie wyników z poprzedniego żądania listy. Dzięki temu wynik żądania listy zawiera tylko wpisy, które od tego czasu się zmieniły. Wszystkie zdarzenia usunięte od czasu poprzedniego żądania listy będą zawsze dostępne w zestawie wyników i nie można ustawić wartości False dla ustawienia showDeleted.
Istnieje kilka parametrów zapytania, których nie można określić razem z parametrem nextSyncToken, aby zapewnić spójność stanu klienta.

To są:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
Wszystkie pozostałe parametry zapytania powinny być takie same jak podczas początkowej synchronizacji, aby uniknąć niezdefiniowanego działania. Gdy syncToken wygaśnie, serwer odpowie z kodem odpowiedzi 410 GONE, a klient powinien wyczyścić pamięć i wykonać pełną synchronizację bez żadnego syncToken.
Dowiedz się więcej o synchronizacji przyrostowej.
Opcjonalny. Domyślnie zwracane są wszystkie wpisy.
timeMax datetime Górna granica czasu rozpoczęcia zdarzenia (wyłącznie), według której można filtrować. Opcjonalnie. Domyślnie nie można filtrować według czasu rozpoczęcia. Musi to być sygnatura czasowa RFC3339 z obowiązkowym przesunięciem strefy czasowej, np. 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Możesz podać milisekundy, ale są one ignorowane. Jeśli ustawiona jest wartość timeMin, wartość timeMax musi być większa niż timeMin.
timeMin datetime Dolna granica czasu zakończenia zdarzenia (wyłącznie), według której można filtrować. Opcjonalnie. Domyślnie nie można filtrować według czasu zakończenia. Musi to być sygnatura czasowa RFC3339 z obowiązkowym przesunięciem strefy czasowej, np. 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Możesz podać milisekundy, ale są one ignorowane. Jeśli ustawiona jest zasada timeMax, wartość timeMin musi być mniejsza niż timeMax.
timeZone string Strefa czasowa używana w odpowiedzi. Opcjonalnie. Wartość domyślna to strefa czasowa kalendarza.
updatedMin datetime Dolna granica czasu ostatniej modyfikacji zdarzenia (jako sygnatura czasowa RFC3339), według której można filtrować. Jeśli podasz wartość, wpisy usunięte od tego momentu będą zawsze uwzględniane niezależnie od wartości showDeleted. Opcjonalnie. Domyślnie nie można filtrować według czasu ostatniej modyfikacji.

Upoważnienie

To żądanie umożliwia autoryzację z co najmniej jednym z tych zakresów:

Zakres
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

Więcej informacji znajdziesz na stronie Uwierzytelnianie i autoryzacja.

Treść żądania

Nie podawaj treści żądania z tą metodą.

Odpowiedź

Jeśli operacja się uda, metoda zwróci treść odpowiedzi w następującej strukturze:

{
  "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
  ]
}
nazwa usługi, Wartość Opis Uwagi
kind string Typ kolekcji („calendar#events”).
etag etag ETag kolekcji.
summary string Nazwa kalendarza. Tylko do odczytu.
description string Opis kalendarza. Tylko do odczytu.
updated datetime Czas ostatniej modyfikacji kalendarza (w postaci sygnatury czasowej RFC3339). Tylko do odczytu.
timeZone string Strefa czasowa kalendarza. Tylko do odczytu.
accessRole string Rola dostępu użytkownika do tego kalendarza. Tylko do odczytu. Możliwe wartości:
  • „none” – użytkownik nie ma dostępu.
  • „freeBusyReader” – użytkownik ma dostęp do odczytu informacji o stanie Wolny/Zajęty.
  • „reader” – użytkownik ma uprawnienia do odczytu kalendarza. Wydarzenia prywatne będą widoczne dla użytkowników z dostępem do odczytu, ale szczegóły wydarzenia będą ukryte.
  • „writer” – użytkownik ma uprawnienia do odczytu i zapisu w kalendarzu. Wydarzenia prywatne będą widoczne dla użytkowników z uprawnieniami zapisu, a szczegóły wydarzenia będą widoczne.
  • „owner” – użytkownik jest właścicielem kalendarza. Ta rola ma wszystkie uprawnienia roli zapisującego z dodatkową możliwością wyświetlania list kontroli dostępu i manipulowania nimi.
defaultReminders[] list Domyślne przypomnienia w kalendarzu dla uwierzytelnionego użytkownika. Te przypomnienia dotyczą wszystkich wydarzeń w tym kalendarzu, które nie mają ich bezpośrednio przesłania (czyli nie mają dla reminders.useDefault wartości Prawda).
defaultReminders[].method string Metoda używana przez to przypomnienie. Możliwe wartości:
  • „email” – przypomnienia są wysyłane e-mailem.
  • „popup” – przypomnienia są wysyłane w wyskakującym okienku w interfejsie.

Wymagane podczas dodawania przypomnienia.

 z możliwością zapisu
defaultReminders[].minutes integer Liczba minut przed rozpoczęciem wydarzenia, na którą powinno zostać aktywowane przypomnienie. Prawidłowe wartości mieszczą się w zakresie od 0 do 40 320 (4 tygodnie w minutach).

Wymagane podczas dodawania przypomnienia.

 z możliwością zapisu
nextPageToken string Token użyty do uzyskania dostępu do następnej strony tego wyniku. Pomijany, jeśli nie są dostępne żadne dalsze wyniki. W takim przypadku podano nextSyncToken.
items[] list Lista wydarzeń w kalendarzu.
nextSyncToken string Token użyty później do pobrania tylko tych wpisów, które zmieniły się od czasu zwrócenia tego wyniku. Pominięta, jeśli dostępne są dalsze wyniki. W takim przypadku podano nextPageToken.

Przykłady

Uwaga: dostępne dla tej metody przykłady kodu nie odzwierciedlają wszystkich obsługiwanych języków programowania. Listę obsługiwanych języków znajdziesz na stronie z bibliotekami klienta.

Java

Używa biblioteki klienta 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

Używa biblioteki klienta Pythona.

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

Korzysta z biblioteki klienta 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

Używa biblioteki klienta 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?

Wypróbuj

Użyj eksploratora interfejsów API poniżej, aby wywołać tę metodę w aktywnych danych i zobaczyć odpowiedź.