Events: list

Zwraca wydarzenia w określonym kalendarzu. Wypróbuj teraz

Żą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 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ć wiele razy, aby zwracać zdarzenia różnych typów. Jeśli nie zostanie ustawiony, zwraca wszystkie typy zdarzeń.

Akceptowane wartości:
  • „birthday”: specjalne wydarzenia całodniowe, które powtarzają się co roku.
  • „default”: zwykłe wydarzenia.
  • „focusTime”: zdarzenia czasu skupienia.
  • „fromGmail”: wydarzenia z Gmaila.
  • „outOfOffice”: wydarzenia poza biurem.
  • „workingLocation”: wydarzenia 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 iCalendar.
maxAttendees integer Maksymalna liczba uczestników, których należy 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ń zwracanych na jednej stronie wyników. Liczba zdarzeń na stronie wyników może być mniejsza od tej wartości lub może nie być ich wcale, nawet jeśli istnieje więcej zdarzeń pasujących do zapytania. Niekompletne strony można wykryć na podstawie niepustego pola nextPageToken w odpowiedzi. Domyślna wartość to 250 zdarzeń. Rozmiar strony nigdy nie może przekraczać 2500 zdarzeń. Opcjonalnie.
orderBy string Kolejność zdarzeń zwróconych w wyniku. Opcjonalnie. Domyślnie jest to nieokreślona, stabilna kolejność.

Akceptowane wartości:
  • „startTime”: sortowanie według daty i godziny rozpoczęcia (rosnąco). Jest to dostępne tylko w przypadku zapytań dotyczących pojedynczych zdarzeń (czyli gdy parametr singleEvents ma wartość True).
  • „updated”: sortuj według czasu ostatniej modyfikacji (rosnąco).
pageToken string Token określający, którą stronę wyników należy zwrócić. 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 wielokrotnie, aby zwracać zdarzenia spełniające wszystkie podane ograniczenia.
q string Wyszukiwane terminy w formie tekstu swobodnego, które pozwalają znaleźć wydarzenia 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 predefiniowanych słów kluczowych we wszystkich tłumaczeniach tytułów wyświetlanych w przypadku zdarzeń dotyczących lokalizacji miejsca pracy, nieobecności i czasu skupienia. Na przykład wyszukanie „Biuro” lub „Bureau” zwraca zdarzenia dotyczące lokalizacji miejsca pracy typu officeLocation, a wyszukanie „Poza biurem” lub „Abwesend” zwraca zdarzenia dotyczące nieobecności w biurze. Opcjonalnie.
sharedExtendedProperty string Ograniczenie właściwości rozszerzonych określone jako propertyName=value. Pasuje tylko do udostępnionych właściwości. Ten parametr może być powtarzany wielokrotnie, aby zwracać zdarzenia spełniające wszystkie podane ograniczenia.
showDeleted boolean Określa, czy w wyniku mają być uwzględniane usunięte zdarzenia (w przypadku których parametr status ma wartość „cancelled”). Anulowane wystąpienia wydarzeń cyklicznych (ale nie samo wydarzenie cykliczne) będą nadal uwzględniane, jeśli wartości showDeleted i singleEvents to „false”. Jeśli wartości showDeleted i singleEvents to „True”, zwracane są tylko pojedyncze wystąpienia usuniętych wydarzeń (ale nie podstawowe wydarzenia cykliczne). Opcjonalnie. Wartość domyślna to False (fałsz).
showHiddenInvitations boolean Określa, czy w wyniku mają być uwzględnione ukryte zaproszenia. Opcjonalnie. Wartość domyślna to False (fałsz).
singleEvents boolean Określa, czy wydarzenia cykliczne mają być rozwijane do postaci wystąpień i czy mają być zwracane tylko pojedyncze wydarzenia jednorazowe i wystąpienia wydarzeń cyklicznych, 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 tego żądania listy będzie zawierać tylko wpisy, które uległy zmianie od tego czasu. Wszystkie wydarzenia usunięte od czasu poprzedniego żądania listy będą zawsze znajdować się w zestawie wyników i nie można ustawić wartości showDeleted na False.
Aby zapewnić spójność stanu klienta, nie można określić kilku parametrów zapytania razem z parametrem nextSyncToken.

Są to:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
 Wszystkie pozostałe parametry zapytania powinny być takie same jak w przypadku początkowej synchronizacji, aby uniknąć nieokreślonego zachowania. Jeśli syncToken wygaśnie, serwer odpowie kodem odpowiedzi 410 GONE, a klient powinien wyczyścić pamięć i przeprowadzić pełną synchronizację bez syncToken.
Więcej informacji o synchronizacji przyrostowej
 Opcjonalnie. Domyślnie zwracane są wszystkie wpisy.
timeMax datetime Górna granica (wyłączna) czasu rozpoczęcia wydarzenia, według której można filtrować. Opcjonalnie. Domyślnie filtrowanie według czasu rozpoczęcia 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 są one ignorowane. Jeśli ustawiona jest wartość timeMin, wartość timeMax musi być większa niż timeMin.
timeMin datetime Dolna granica (wyłączna) czasu zakończenia zdarzenia, według której można filtrować. Opcjonalnie. Domyślnie filtrowanie według czasu zakończenia nie jest włą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 są one ignorowane. 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 (sygnatura czasowa RFC3339) do filtrowania. Jeśli ta opcja jest określona, wpisy usunięte od tego czasu będą zawsze uwzględniane niezależnie od wartości parametru showDeleted. Opcjonalnie. Domyślnie filtrowanie według czasu ostatniej modyfikacji jest wyłączone.

Autoryzacja

Ta prośba umożliwia autoryzację w 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
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

Więcej informacji znajdziesz na stronie Uwierzytelnianie i autoryzacja.

Treść żądania

Nie podawaj treści żądania w przypadku tej metody.

Odpowiedź

Jeśli operacja się uda, metoda zwróci odpowiedź w poniższym 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 (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 dostęp do informacji o stanie Wolny/Zajęty w trybie odczytu.
  • „reader” – użytkownik ma dostęp do kalendarza w trybie odczytu. Wydarzenia prywatne będą widoczne dla użytkowników z dostępem do odczytu, ale szczegóły wydarzeń będą ukryte.
  • „writerWithoutPrivateAccess” – użytkownik ma dostęp do kalendarza w trybie odczytu i zapisu. Wydarzenia prywatne będą widoczne dla użytkowników z dostępem writerWithoutPrivateAccess, ale szczegóły wydarzeń będą ukryte.
  • „writer” – użytkownik ma dostęp do kalendarza w trybie odczytu i zapisu. Wydarzenia prywatne będą widoczne dla użytkowników z uprawnieniami do edycji, a szczegóły wydarzeń będą widoczne.
  • „owner” – użytkownik ma dostęp do kalendarza jako menedżer. Ta rola ma wszystkie uprawnienia roli autora, a dodatkowo umożliwia wyświetlanie i modyfikowanie poziomów dostępu innych użytkowników.

defaultReminders[] list Domyślne przypomnienia w kalendarzu uwierzytelnionego użytkownika. Te przypomnienia dotyczą wszystkich wydarzeń w tym kalendarzu, które nie mają ich wyraźnie zastąpionych (tzn. nie mają ustawionej wartości reminders.useDefault na „Prawda”).
defaultReminders[].method string Metoda użyta 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.

 z możliwością zapisu,
defaultReminders[].minutes integer Liczba minut przed rozpoczęciem wydarzenia, po upływie których ma się pojawić przypomnienie. Prawidłowe wartości to od 0 do 40320 (4 tygodnie w minutach).

Wymagane podczas dodawania przypomnienia.

 z możliwością zapisu,
nextPageToken string Token używany do uzyskiwania dostępu do następnej strony tego wyniku. Pomijany, jeśli nie ma więcej wyników. W takim przypadku podawany jest znak nextSyncToken.
items[] list Lista wydarzeń w kalendarzu.
nextSyncToken string Token używany w późniejszym czasie do pobierania tylko tych wpisów, które uległy zmianie od momentu zwrócenia tego wyniku. Pomijany, jeśli dostępne są dalsze wyniki. W takim przypadku podawany jest parametr nextPageToken.

Wypróbuj

Użyj narzędzia APIs Explorer poniżej, aby wywołać tę metodę na danych na żywo i zobaczyć odpowiedź.