Events: list

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

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

Żądanie

Żą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 obecnie zalogowanego użytkownika, użyj słowa kluczowego „primary”.
Opcjonalne parametry zapytania
alwaysIncludeEmail boolean Wycofane i ignorowane. Wartość w polu email dla organizatora, twórcy i uczestników jest zawsze zwracana, nawet jeśli nie jest dostępny prawdziwy adres e-mail (ta wartość zostanie wygenerowana i nie będzie działać).
eventTypes string Typy zdarzeń do zwrócenia. Opcjonalnie. Wartość domyślna to ["default", "outOfOffice", "focusTime"]. Dostępna jest tylko wartość domyślna, chyba że zarejestrujesz się w wersji testowej dla deweloperów.
iCalUID string Określa identyfikator zdarzenia w formacie iCalendar, który ma być podany w odpowiedzi. Opcjonalnie. Użyj go, jeśli chcesz wyszukać wydarzenie według jego identyfikatora iCalendar.
maxAttendees integer Maksymalna liczba uczestników uwzględnionych w odpowiedzi. Jeśli uczestników jest więcej niż określona, zwracany jest tylko uczestnik. Opcjonalnie.
maxResults integer Maksymalna liczba zdarzeń zwróconych na jednej stronie wyników. Liczba zdarzeń na wyświetlonej stronie może być mniejsza od tej wartości lub w ogóle się nie wyświetlać, nawet jeśli jest więcej zdarzeń pasujących do zapytania. Niepełne strony mogą zostać wykryte przez niepuste pole nextPageToken w odpowiedzi. Domyślnie jest to 250 zdarzeń. Rozmiar strony nie może przekraczać 2500 zdarzeń. Opcjonalnie.
orderBy string Kolejność zdarzeń w wynikach. Opcjonalnie. Domyślne ustawienie to nieokreślona, stabilna kolejność.

Akceptowane wartości:
  • startTime”: sortowanie według daty/godziny rozpoczęcia (rosnąco). Ta funkcja jest dostępna tylko w przypadku wysyłania zapytań do pojedynczych zdarzeń (parametr singleEvents ma wartość Prawda).
  • updated”: sortowanie według czasu ostatniej modyfikacji (rosnąco).
pageToken string Token określający stronę wyników do zwrócenia. Opcjonalnie.
privateExtendedProperty string Rozszerzone ograniczenie właściwości określone jako Element propertyName=wartość. Pasuje tylko do właściwości prywatnych. Ten parametr może się powtarzać wiele razy, aby zwracać zdarzenia spełniające wszystkie ograniczenia.
q string Bezpłatne wyszukiwane hasła, aby znaleźć wydarzenia pasujące do tych pól: summary, description, location, displayName uczestnika, email uczestnika. Opcjonalnie.
sharedExtendedProperty string Rozszerzone ograniczenie właściwości określone jako Element propertyName=wartość. Pasuje tylko do udostępnionych usług. Ten parametr może się powtarzać wiele razy, aby zwracać zdarzenia spełniające wszystkie ograniczenia.
showDeleted boolean Określa, czy w wynikach ma być usunięte zdarzenia (status to równa się „cancelled”). Anulowane wystąpienia wydarzeń cyklicznych (ale nie te, które się znajdują) nadal będą uwzględniane, jeśli showDeleted i singleEvents są fałszywe. Jeśli showDeleted i singleEvents mają wartość Prawda, zwracane są tylko pojedyncze wystąpienia usuniętych wydarzeń (ale nie wydarzenia cykliczne). Opcjonalnie. Wartość domyślna to Fałsz.
showHiddenInvitations boolean Określa, czy uwzględnić w wynikach ukryte zaproszenia. Opcjonalnie. Wartość domyślna to Fałsz.
singleEvents boolean Określa, czy rozwinąć wydarzenia cykliczne do instancji i zwrócić tylko pojedyncze wydarzenia jednorazowe i wystąpienia cykliczne, ale nie same wydarzenia cykliczne. Opcjonalnie. Wartość domyślna to Fałsz.
syncToken string Token uzyskany z pola nextSyncToken zwrócony na ostatniej stronie wyników z poprzedniego żądania listy. W wyniku tego żądania listy wyświetlane są tylko wpisy, które od tego czasu uległy zmianie. Wszystkie zdarzenia usunięte od poprzedniego żądania listy zawsze będą dostępne w wynikach i nie można ustawić wartości showDeleted na Fałsz.
Aby zapewnić spójność stanu klienta, nie można określać niektórych parametrów zapytania razem z atrybutem nextSyncToken.

Są to:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
Jeśli syncToken wygaśnie, serwer zwróci kod odpowiedzi 410 GONE, a klient powinien wyczyścić pamięć i przeprowadzić pełną synchronizację bez użycia syncToken.
Dowiedz się więcej o przyrostowej synchronizacji.
Opcjonalnie. Domyślnie zwracane są wszystkie wpisy.
timeMax datetime Górna granica (wyłączna) godziny rozpoczęcia zdarzenia, według którego chcesz filtrować. Opcjonalnie. Ustawieniem domyślnym nie jest filtrowanie według czasu rozpoczęcia. Musi to być sygnatura czasowa RFC3339 z wymaganym przesunięciem strefy czasowej, na przykład 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Wartość w milisekundach może być podana, ale jest ignorowana. Jeśli zasada timeMin jest skonfigurowana, wartość timeMax musi być większa niż timeMin.
timeMin datetime Dolna granica (wyłączna) czasu zakończenia zdarzenia, według którego ma być filtrowane. Opcjonalnie. Ustawieniem domyślnym nie jest filtrowanie według czasu zakończenia. Musi to być sygnatura czasowa RFC3339 z wymaganym przesunięciem strefy czasowej, na przykład 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Wartość w milisekundach może być podana, ale jest ignorowana. Jeśli ustawiona jest wartość timeMax, wartość timeMin musi być mniejsza niż timeMax.
timeZone string Strefa czasowa w odpowiedzi. Opcjonalnie. Domyślnie jest 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 zostanie określony, wpisy usunięte od tego czasu będą zawsze uwzględniane, niezależnie od showDeleted. Opcjonalnie. Ustawieniem domyślnym nie jest filtrowanie według czasu ostatniej modyfikacji.

Upoważnienie

To żądanie umożliwia autoryzację przy użyciu co najmniej jednego 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 uwierzytelniania i autoryzacji.

Treść żądania

Nie udostępniaj treści żądania tą metodą.

Odpowiedź

Jeśli operacja się uda, metoda zwróci odpowiedź w następującym formacie:

{
  "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 Tytuł kalendarza. Tylko do odczytu.
description string Opis kalendarza. Tylko do odczytu.
updated datetime Czas ostatniej modyfikacji kalendarza (jako sygnatura czasowa RFC3339). Tylko do odczytu.
timeZone string Strefa czasowa kalendarza. Tylko do odczytu.
accessRole string Rola użytkownika w tym kalendarzu. Tylko do odczytu. Możliwe wartości:
  • none” – użytkownik nie ma dostępu.
  • freeBusyReader” – użytkownik ma dostęp do informacji o stanie Wolny/Zajęty.
  • reader” – użytkownik ma dostęp do kalendarza. Prywatne wydarzenia będą widoczne dla użytkowników z dostępem do odczytu, ale szczegóły wydarzeń 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 zapisującego, a ich szczegóły będą widoczne.
  • owner” – użytkownik jest właścicielem kalendarza. Ta rola ma wszystkie uprawnienia roli zapisującego, a dodatkowo umożliwia wyświetlanie i modyfikowanie list kontroli dostępu.
defaultReminders[] list Domyślne przypomnienia w kalendarzu dotyczące uwierzytelnionego użytkownika. Przypomnienia mają zastosowanie do wszystkich wydarzeń w tym kalendarzu, które nie mają na nich wyraźnego znaczenia (tzn. gdy reminders.useDefault nie mają 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 interfejsu.

Wymagane podczas dodawania przypomnienia.

zapisywalny
defaultReminders[].minutes integer Liczba minut przed rozpoczęciem wydarzenia, w którym powinno się włączyć przypomnienie. Prawidłowe wartości to 0 – 40320 (4 tygodnie w minutach).

Wymagane podczas dodawania przypomnienia.

zapisywalny
nextPageToken string Token, dzięki któremu można uzyskać dostęp do następnej strony tego wyniku. Pominięto, jeśli nie są dostępne żadne dalsze wyniki. W takim przypadku podano nextSyncToken.
items[] list Lista wydarzeń w kalendarzu.
nextSyncToken string Token używany później w celu pobrania tylko wpisów, które zostały zmienione od chwili zwrócenia tego wyniku. Pominięto, 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 w języku 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 dla języka 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

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

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