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 Wycofano i zignorowano.
eventTypes string Typy zdarzeń do zwrócenia. Opcjonalnie. Ten parametr można powtarzać wiele razy, aby zwracać zdarzenia różnego rodzaju. Jeśli zasada jest nieskonfigurowana, zwraca wszystkie typy zdarzeń.

Akceptowane wartości:
  • default”: zwykłe wydarzenia.
  • focusTime”: wydarzenia typu czas skupienia.
  • outOfOffice”: wydarzenia poza biurem.
  • workingLocation”: zdarzenia dotyczące lokalizacji miejsca pracy.
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 uczestnicy mają więcej niż określona liczba uczestników, 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ć żadnych zdarzeń nawet wtedy, gdy do zapytania jest więcej zdarzeń. Niepełne strony mogą zostać wykryte w odpowiedzi na niepuste pole nextPageToken. Domyślnie wartością jest 250 zdarzeń. Rozmiar strony nigdy nie może przekraczać 2500 zdarzeń. Opcjonalnie.
orderBy string Kolejność zdarzeń zwracanych w wyniku. Opcjonalnie. Wartość domyślna to nieokreślona, stabilna kolejność.

Akceptowane wartości:
  • startTime”: sortowanie według daty/godziny rozpoczęcia (rosnąco). Jest to możliwe tylko w przypadku zapytań dotyczących pojedynczych zdarzeń (np.parametr singleEvents ma wartość True).
  • updated”: kolejność według czasu ostatniej modyfikacji (rosnąco).
pageToken string Token określający stronę wyników, która ma zostać zwrócona. Opcjonalnie.
privateExtendedProperty string Ograniczenie właściwości rozszerzonych określono w postaci właściwościpropertyName=wartość. Pasuje tylko do usług prywatnych. Ten parametr może być powtórzony kilka razy, aby zwrócić zdarzenia pasujące do wszystkich podanych ograniczeń.
q string Wyszukiwane hasła zawierające dowolny tekst w następujących polach:
  • summary
  • description
  • location
  • displayName uczestnika
  • email uczestnika
  • displayName organizatora
  • email organizatora
  • 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 tłumaczeń nazw miejsca pracy, nieobecności w biurze i wydarzeń związanych z czasem skupienia. Na przykład wyszukanie hasła „Biuro” lub „Biuro” zwróci zdarzenia związane z lokalizacją miejsca pracy typu officeLocation, a wyszukiwanie „Poza biurem” lub „Abwesend” zwróci zdarzenia „poza biurem”. Opcjonalnie.

sharedExtendedProperty string Ograniczenie właściwości rozszerzonych określono w postaci właściwościpropertyName=wartość. Pasuje tylko do udostępnionych usług. Ten parametr może być powtórzony kilka 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 polem 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 zarówno zdarzenia showDeleted, jak 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ścią domyślną jest Fałsz.
showHiddenInvitations boolean Określa, czy w wyniku mają być uwzględnione ukryte zaproszenia. Opcjonalnie. Wartością domyślną jest Fałsz.
singleEvents boolean Określa, czy wydarzenia cykliczne mają się pojawiać w wystąpieniach i zwracają tylko pojedyncze wydarzenia oraz wystąpienia powtarzających się wydarzeń, ale nie same wydarzenia cykliczne. Opcjonalnie. Wartością domyślną jest Fałsz.
syncToken string Token uzyskany z pola nextSyncToken zwróconego na ostatniej stronie wyników poprzedniego żądania listy. Dzięki temu wynik żądania listy zawiera tylko wpisy, które zmieniły się od tego czasu. Wszystkie zdarzenia usunięte od czasu poprzedniego żądania listy będą zawsze w zestawie wyników i nie można ustawić wartości showDeleted na wartość Fałsz.
Istnieje kilka parametrów zapytania, których nie można używać razem z parametrem nextSyncToken w celu zapewnienia spójności stanu klienta.

To są:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
Wszystkie pozostałe parametry zapytania powinny być takie same jak przy początkowej synchronizacji, aby uniknąć nieokreślonego zachowania. Jeśli syncToken wygaśnie, serwer wyśle w odpowiedzi kod odpowiedzi 410 GONE, a klient powinien wyczyścić pamięć i przeprowadzić pełną synchronizację bez żadnego syncToken.
Dowiedz się więcej o synchronizacji przyrostowej.
Opcjonalna. Domyślnie zwracane są wszystkie wpisy.
timeMax datetime Górna granica czasu rozpoczęcia zdarzenia (bez jej uwzględnienia), według której ma być filtrowany. Opcjonalnie. Domyślnie filtr nie jest filtrowany 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żna podać milisekundy, ale są one ignorowane. Jeśli ustawiona jest wartość timeMin, timeMax musi mieć wartość większą niż timeMin.
timeMin datetime Dolna granica (wyłącznie) czasu zakończenia zdarzenia, według którego ma być filtrowany. Opcjonalnie. Domyślnie filtr nie jest filtrowany według godziny 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żna podać milisekundy, ale są one ignorowane. Jeśli skonfigurowano timeMax, wartość timeMin musi być mniejsza niż timeMax.
timeZone string Strefa czasowa używana w odpowiedzi. Opcjonalnie. Domyślną wartością jest strefa czasowa kalendarza.
updatedMin datetime Dolna granica czasu ostatniej modyfikacji zdarzenia (jako sygnatura czasowa RFC3339), według której ma być filtrowana. Jeśli określisz wartość, wpisy usunięte od tego czasu będą zawsze uwzględniane niezależnie od ustawienia showDeleted. Opcjonalnie. Domyślnie filtr nie jest filtrowany 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 za pomocą tej metody.

Odpowiedź

Jeśli operacja się uda, metoda zwróci odpowiedź o 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 Godzina ostatniej modyfikacji kalendarza (jako sygnatura czasowa RFC3339). Tylko do odczytu.
timeZone string Strefa czasowa kalendarza. Tylko do odczytu.
accessRole string Rola użytkownika dotycząca dostępu do tego kalendarza. 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 uprawnienia do odczytu kalendarza. Wydarzenia prywatne będą widoczne dla użytkowników z dostępem do odczytu, ale ich szczegóły 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 do zapisu, a szczegóły wydarzeń 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 ich nie zastępują (czyli nie mają funkcji reminders.useDefault ustawionej jako 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 UI.

Wymagane przy dodawaniu przypomnienia.

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

Wymagane przy dodawaniu przypomnienia.

z możliwością zapisu
nextPageToken string Token używany do przejścia na następną stronę danego wyniku. Ta wartość jest pomijana, 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 później do pobrania tylko tych wpisów, które zmieniły się od zwrócenia tego wyniku. Ta wartość jest pomijana, jeśli dostępne są dalsze wyniki. W takim przypadku podana jest wartość 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

Wykorzystuje bibliotekę 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ę na aktywnych danych i zobaczyć odpowiedź.