Events: list

Zwraca wydarzenia w wybranym kalendarzu. 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 głównego kalendarza aktualnie zalogowanego użytkownika, użyj słowa kluczowego „primary”.
Opcjonalne parametry zapytania
alwaysIncludeEmail boolean Wycofane i ignorowane.
eventTypes string Typy zdarzeń do zwrócenia. Opcjonalnie: Ten parametr można powtórzyć kilka razy, aby zwracać zdarzenia różnych typów. Jeśli nie zostanie ustawiony, zwraca wszystkie typy zdarzeń.

Akceptowane wartości:
  • „birthday”: specjalne całodniowe wydarzenia cykliczne co roku.
  • „default”: zwykłe zdarzenia.
  • „focusTime”: wydarzenia typu czas skupienia.
  • „fromGmail”: wydarzenia z Gmaila.
  • „outOfOffice”: wydarzenia poza biurem.
  • „workingLocation”: zdarzenia dotyczące lokalizacji miejsca pracy.
iCalUID string Określa identyfikator wydarzenia w formacie iCalendar, który ma być podany w odpowiedzi. Opcjonalnie: Użyj tej opcji, jeśli chcesz wyszukać wydarzenie według jego identyfikatora iKalendarz.
maxAttendees integer Maksymalna liczba uczestników, których można uwzględnić w odpowiedzi. Jeśli jest ich więcej, zwracany jest tylko jeden uczestnik. Opcjonalnie:
maxResults integer Maksymalna liczba zdarzeń zwracanych na jednej stronie wyników. Liczba zdarzeń na stronie wynikowej może być mniejsza od tej wartości lub może nie być w ogóle żadnego, nawet jeśli pasuje do zapytania więcej zdarzeń. Niekompletne 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ń zwróconych w wyniku. Opcjonalnie: Wartość domyślna to nieokreślona, stabilna kolejność.

Akceptowane wartości:
  • „startTime”: kolejność według daty/godziny rozpoczęcia (rosnąca). Ta opcja jest dostępna tylko przy wysyłaniu zapytań o pojedyncze zdarzenia (np.parametr singleEvents ma wartość True).
  • „updated”: kolejność według czasu ostatniej modyfikacji (rosnąco).
pageToken string Token określający, która strona z wynikami ma zostać zwrócona. Opcjonalnie:
privateExtendedProperty string Ograniczenie właściwości rozszerzonych określone jako propertyName=value. Dopasowuje tylko właściwości prywatne. Ten parametr może być powtarzany wielokrotnie, aby zwracać zdarzenia, które pasują do wszystkich podanych ograniczeń.
q string wyszukiwanie w postaci tekstu dowolnego, aby znaleźć zdarzenia pasujące do tych terminów w tych polach:
  • summary
  • description
  • location
  • displayName uczestnika
  • email uczestnika
  • organizatora displayName
  • organizatora email
  • workingLocationProperties.officeLocation.buildingId
  • workingLocationProperties.officeLocation.deskId
  • workingLocationProperties.officeLocation.label
  • workingLocationProperties.customLocation.label

Te wyszukiwane słowa są też dopasowywane do zdefiniowanych wstępnie słów kluczowych we wszystkich tłumaczeniach tytułu wyświetlanego w przypadku wydarzeń związanych z miejscem pracy, nieobecnością w pracy i czasem nauki. Na przykład wyszukiwanie „Biuro” lub „Bureau” spowoduje zwrócenie zdarzeń związanych z lokalizacją pracy typu officeLocation, natomiast wyszukiwanie „Nieobecność” lub „Abwesend” spowoduje zwrócenie zdarzeń związanych z nieobecnością. Opcjonalnie:
sharedExtendedProperty string Ograniczenie właściwości rozszerzonych określone jako propertyName=value. Pasuje tylko do właściwości udostępnionych. Ten parametr może być powtórzony wiele razy, aby zwracać zdarzenia, które pasują do wszystkich podanych ograniczeń.
showDeleted boolean Określa, czy w wyniku mają zostać uwzględnione usunięte wydarzenia (gdy status równa się „cancelled”). Anulowane wystąpienia cyklicznych zdarzeń (ale nie samo cykliczne zdarzenie) będą uwzględniane, jeśli wartości showDeleted i singleEvents mają wartość „False”. Jeśli showDeleted i singleEvents mają wartość Prawda, zwracane są tylko pojedyncze wystąpienia usuniętych zdarzeń (ale nie ich podstawy, czyli wydarzenia cykliczne). Opcjonalnie: Wartość domyślna to False (fałsz).
showHiddenInvitations boolean Określa, czy w wynikach mają być uwzględnione ukryte zaproszenia. Opcjonalnie: Wartość domyślna to False (fałsz).
singleEvents boolean Określa, czy należy rozwinąć cykliczne zdarzenia na wystąpienia i zwrócić tylko pojedyncze zdarzenia oraz wystąpienia cyklicznych zdarzeń, a nie same cykliczne zdarzenia. 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 tego żądania listy zawiera tylko wpisy, które zmieniły się od tego czasu. Wszystkie zdarzenia usunięte od czasu poprzedniego żądania listy zawsze będą znajdować się w zestawie wyników i nie można ustawić zasady showDeleted na wartość Fałsz.
Aby zapewnić spójność stanu klienta, istnieje kilka parametrów zapytania, których nie można określać razem z parametrem nextSyncToken.

Należą do nich:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
 Aby uniknąć nieokreślonego zachowania, wszystkie pozostałe parametry zapytania powinny być takie same jak w przypadku początkowej synchronizacji. Jeśli komunikat syncToken wygaśnie, serwer odpowie z kodem odpowiedzi 410 GONE i klient powinien wyczyścić pamięć urządzenia i przeprowadzić pełną synchronizację bez użycia funkcji syncToken.
Dowiedz się więcej o synchronizacji przyrostowej.
Opcjonalna. Domyślnie zwracane są wszystkie wpisy.
timeMax datetime Górna granica (wyłącznie) określająca godzinę rozpoczęcia zdarzenia, według której ma być filtrowane. Opcjonalnie: Domyślnie filtrowanie według czasu rozpoczęcia jest wyłączone. Musi być sygnaturą czasową w formacie RFC3339 z obowiązkowym przesunięciem strefy czasowej, np. 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Można podać milisekundy, ale zostaną one zignorowane. Jeśli ustawiono timeMin, wartość timeMax musi być większa niż timeMin.
timeMin datetime Dolna granica (wyłącznie) określająca czas zakończenia zdarzenia, według którego ma być filtrowane. Opcjonalnie: Domyślnie filtrowanie według czasu zakończenia jest wyłączone. Musi to być sygnatura czasowa w formacie RFC3339 z obowiązkowym przesunięciem strefy czasowej, np. 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Można podać milisekundy, ale zostaną one zignorowane. Jeśli ustawiona jest wartość timeMax, wartość timeMin musi być mniejsza niż timeMax.
timeZone string Strefa czasowa użyta w odpowiedzi. Opcjonalnie: Domyślnie jest to strefa czasowa kalendarza.
updatedMin datetime Dolna granica czasu ostatniej modyfikacji zdarzenia (w postaci sygnatury czasowej RFC3339), według którego ma być filtrowany. Jeśli to pole jest określone, wpisy usunięte od tego czasu będą zawsze uwzględniane niezależnie od wartości parametru showDeleted. Opcjonalnie: Domyślnie nie filtruje według czasu ostatniej modyfikacji.

Autoryzacja

Ta prośba 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 dotyczącej uwierzytelniania i autoryzacji.

Treść żądania

W przypadku tej metody nie podawaj treści żądania.

Odpowiedź

Jeśli operacja się powiedzie, metoda zwróci odpowiedź o tej 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 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 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 uprawnienia tylko do odczytu informacji o stanie Wolny/Zajęty.
  • „reader” – użytkownik ma dostęp tylko do odczytu kalendarza. Wydarzenia prywatne będą widoczne dla użytkowników z dostępem tylko 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 dostępem do funkcji pisania, a szczegóły wydarzeń będą widoczne.
  • „owner” – użytkownik jest właścicielem kalendarza. Ta rola ma wszystkie uprawnienia roli autora, a dodatkowo umożliwia wyświetlanie i modyfikowanie list dostępu.
defaultReminders[] list Domyślne przypomnienia w kalendarzu dla uwierzytelnionego użytkownika. Te przypomnienia dotyczą wszystkich wydarzeń w tym kalendarzu, które ich nie zastępują (tj. nie mają wartości reminders.useDefault ustawionej na Prawda).
defaultReminders[].method string Metoda użyta w tym przypomnieniu. Możliwe wartości:
  • „email” – przypomnienia są wysyłane pocztą e-mail.
  • „popup” – przypomnienia są wysyłane przez wyskakujące okienko w interfejsie.

Wymagany podczas dodawania przypomnienia.

 zapisywalny
defaultReminders[].minutes integer Liczba minut przed rozpoczęciem wydarzenia, kiedy powinno wyświetlić się przypomnienie. Prawidłowe wartości mieszczą się w zakresie od 0 do 40 320 (4 tygodnie w minutach).

Wymagany podczas dodawania przypomnienia.

 zapisywalny
nextPageToken string Token użyty do uzyskania dostępu do następnej strony tego wyniku. Pomijany, jeśli nie ma dostępnych dalszych wyników. W takim przypadku podawana jest wartość nextSyncToken.
items[] list Lista wydarzeń w kalendarzu.
nextSyncToken string Token używany w późniejszym czasie do pobierania tylko tych wpisów, które zmieniły się od czasu zwrócenia tego wyniku. Pomijany, jeśli są dostępne inne wyniki, w którym przypadku jest podawany parametr 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

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

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

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

Użyj poniższego eksploratora interfejsów API, aby wywołać tę metodę na bieżących danych i wyświetlić odpowiedź.