Kalendarze i wydarzenia

Ten przewodnik opisuje kalendarze, wydarzenia i ich wzajemne relacje.

Kalendarze

Kalendarz to zbiór powiązanych wydarzeń oraz dodatkowych metadanych takich jak podsumowanie, domyślna strefa czasowa i lokalizacja. Każdy kalendarz jest identyfikowany przez identyfikator, który jest adresem e-mail. Kalendarze można udostępniać innym osobom. Kalendarze główne należą do powiązanego konta użytkownika, a inne kalendarze należą do jednego właściciela danych.

Wydarzenia

Wydarzenie to obiekt powiązany z konkretną datą lub zakresem czasu. Wydarzenia są identyfikowane przez unikalny identyfikator. Oprócz daty i godziny rozpoczęcia i zakończenia wydarzenia zawierają też inne dane, takie jak podsumowanie, opis, lokalizacja, stan, przypomnienia i załączniki.

Typy zdarzeń

Kalendarz Google obsługuje wydarzenia pojedyncze i cykliczne:

• Wydarzenie pojedyncze to unikalne wystąpienie.
• Wydarzenie cykliczne definiuje wiele wystąpień.

Wydarzenia mogą być też czasowe lub całodniowe:

• Wydarzenie czasowe odbywa się między 2 konkretnymi punktami w czasie. Wydarzenia czasowe używają pól start.dateTime i end.dateTime do określania, kiedy mają się odbyć.
• Wydarzenie całodniowe trwa cały dzień lub kilka kolejnych dni. Wydarzenia całodniowe używają pól start.date i end.date do określania, kiedy mają się odbyć. Pamiętaj, że pole strefy czasowej nie ma znaczenia w przypadku wydarzeń całodniowych.

Zarówno początek, jak i koniec wydarzenia muszą być czasowe lub całodniowe. Na przykład nie można określić start.date i end.dateTime.

Organizatorzy

Wydarzenia mają jednego organizatora , którym jest kalendarz zawierający główną kopię wydarzenia. Wydarzenia mogą też mieć wielu uczestników. Uczestnik to zwykle kalendarz główny zaproszonego użytkownika.

Poniższy diagram przedstawia koncepcyjny związek między kalendarzami, wydarzeniami i innymi powiązanymi elementami:

Kalendarze główne i inne kalendarze

Kalendarz główny to specjalny typ kalendarza powiązany z jednym kontem użytkownika. Ten kalendarz jest tworzony automatycznie dla każdego nowego konta użytkownika, a jego identyfikator zwykle odpowiada głównemu adresowi e-mail użytkownika. Dopóki konto istnieje, kalendarza głównego nie można usunąć ani „odłączyć” od użytkownika. Można go jednak udostępniać innym użytkownikom.

Oprócz kalendarza głównego możesz utworzyć dowolną liczbę innych kalendarzy. Te kalendarze można modyfikować, usuwać i udostępniać innym osobom. Takie kalendarze mają jednego właściciela danych z najwyższymi uprawnieniami, w tym z wyłącznym prawem do usunięcia kalendarza. Nie można obniżyć poziomu dostępu właściciela danych. Właścicielem danych jest początkowo użytkownik, który utworzył kalendarz, ale własność danych można przenieść w interfejsie Kalendarza Google.

Ważne: podczas tworzenia kalendarza zalecamy, aby aplikacja uwierzytelniała się jako zamierzony właściciel danych kalendarza. Możesz użyć przekazywania uprawnień w całej domenie, aby umożliwić aplikacjom działanie w imieniu konkretnego użytkownika. Nie używaj konta usługi do uwierzytelniania. Jeśli do uwierzytelniania używasz konta usługi, właścicielem danych jest konto usługi, co może prowadzić do nieoczekiwanych zachowań. Jeśli na przykład właścicielem danych jest konto usługi, nie można przenieść własności danych.

Kalendarz i lista kalendarzy

Kolekcja Calendars reprezentuje wszystkie istniejące kalendarze. Można jej używać do tworzenia i usuwania kalendarzy. Możesz też pobierać lub ustawiać właściwości globalne udostępniane wszystkim użytkownikom, którzy mają dostęp do kalendarza. Na przykład tytuł kalendarza i domyślna strefa czasowa to właściwości globalne.

CalendarList to zbiór wszystkich wpisów w kalendarzu, które użytkownik dodał do swojej listy (widocznej w panelu po lewej stronie interfejsu internetowego). Możesz jej używać do dodawania i usuwania istniejących kalendarzy z listy użytkownika. Możesz też używać jej do pobierania i ustawiania wartości właściwości kalendarza specyficznych dla użytkownika, takich jak domyślne przypomnienia. Innym przykładem jest kolor pierwszego planu, ponieważ różni użytkownicy mogą mieć ustawione różne kolory dla tego samego kalendarza.

Uwaga: właściciel danych kalendarza nie może usunąć tego kalendarza ze swojej listy kalendarzy.

W tabeli poniżej porównujemy znaczenie operacji w przypadku tych 2 kolekcji:

Operacja	Kalendarze	CalendarList
insert	Tworzy nowy kalendarz pomocniczy. Ten kalendarz jest też dodawany do listy kalendarzy twórcy i nie można go usunąć, chyba że kalendarz zostanie usunięty lub przeniesiony.	Wstawia istniejący kalendarz na listę użytkownika.
delete	Usuwa kalendarz pomocniczy.	Usuwa kalendarz z listy użytkownika.
get	Pobiera metadane kalendarza, np. tytuł i strefę czasową.	Pobiera metadane oraz dostosowanie specyficzne dla użytkownika takie jak kolor lub zastąpienie przypomnień.
patch/update	Modyfikuje metadane kalendarza.	Modyfikuje właściwości kalendarza specyficzne dla użytkownika.

Wydarzenia cykliczne

Niektóre wydarzenia powtarzają się regularnie, np. cotygodniowe spotkania, urodziny i święta. Oprócz różnych godzin rozpoczęcia i zakończenia te powtarzające się wydarzenia są często identyczne.

Wydarzenia są nazywane cyklicznymi , jeśli powtarzają się zgodnie z określonym harmonogramem. Wydarzenia pojedyncze nie są cykliczne i odbywają się tylko raz.

Reguła powtarzania

Harmonogram wydarzenia cyklicznego jest zdefiniowany w 2 częściach:

• pola rozpoczęcia i zakończenia (które definiują pierwsze wystąpienie, tak jakby było to pojedyncze wydarzenie), oraz

• pole powtarzania (które określa, jak wydarzenie ma się powtarzać w czasie).

Pole powtarzania zawiera tablicę ciągów znaków reprezentujących jedną lub kilka RRULE, RDATE lub EXDATE właściwości zgodnie z definicją w RFC 5545.

Właściwość RRULE jest najważniejsza, ponieważ definiuje regularną regułę powtarzania wydarzenia. Składa się z kilku komponentów. Niektóre z nich to:

• FREQ – częstotliwość powtarzania wydarzenia (np. DAILY lub WEEKLY). Wymagane.

• INTERVAL – działa razem z FREQ, aby określić, jak często wydarzenie ma się powtarzać. Na przykład FREQ=DAILY;INTERVAL=2 oznacza raz na 2 dni.

• COUNT – liczba powtórzeń tego wydarzenia.

  Aby określić koniec powtarzania wydarzenia, możesz użyć COUNT lub UNTIL. Nie używaj obu tych elementów w tej samej regule.

• UNTIL – data lub data i godzina, do której wydarzenie ma się powtarzać (włącznie).

• BYDAY – dni tygodnia, w których wydarzenie ma się powtarzać (SU, MO, TU itp.). Inne podobne komponenty to BYMONTH, BYYEARDAY i BYHOUR.

Właściwość RDATE określa dodatkowe daty lub daty i godziny, w których mają się odbywać wystąpienia wydarzenia. Na przykład RDATE;VALUE=DATE:19970101,19970120. Użyj tej opcji, aby dodać dodatkowe wystąpienia, które nie są objęte regułą RRULE.

Właściwość EXDATE jest podobna do RDATE, ale określa daty lub daty i godziny, w których wydarzenie nie powinno się odbywać. Oznacza to, że te wystąpienia powinny zostać wykluczone. Musi to być prawidłowa instancja wygenerowana przez regułę powtarzania.

EXDATE i RDATE mogą mieć strefę czasową i muszą być datami (nie datami i godzinami) w przypadku wydarzeń całodniowych.

Każda z tych właściwości może występować w polu powtarzania wiele razy. Powtarzanie jest definiowane jako suma wszystkich reguł RRULE i RDATE pomniejszona o te, które są wykluczone przez wszystkie reguły EXDATE.

Oto kilka przykładów wydarzeń cyklicznych:

1. Wydarzenie, które odbywa się od 6:00 do 7:00 w każdy wtorek i piątek od 15 września 2015 r. i kończy się po 5. wystąpieniu 29 września 2015 r.:

   ...
   "start": {
     "dateTime": "2015-09-15T06:00:00+02:00",
     "timeZone": "Europe/Zurich"
   },
   "end": {
     "dateTime": "2015-09-15T07:00:00+02:00",
     "timeZone": "Europe/Zurich"
   },
   "recurrence": [
     "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR"
   ],
   ...
   

2. Wydarzenie całodniowe rozpoczynające się 1 czerwca 2015 r. i powtarzające się co 3 dni przez cały miesiąc, z wyłączeniem 10 czerwca, ale z uwzględnieniem 9 i 11 czerwca:

   ...
   "start": {
     "date": "2015-06-01"
   },
   "end": {
     "date": "2015-06-02"
   },
   "recurrence": [
     "EXDATE;VALUE=DATE:20150610",
     "RDATE;VALUE=DATE:20150609,20150611",
     "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3"
   ],
   ...
   

Instancje i wyjątki

Wydarzenie cykliczne składa się z kilku instancji: jego konkretnych wystąpień w różnych momentach. Te instancje działają jak wydarzenia.

Modyfikacje wydarzenia cyklicznego mogą wpływać na całe wydarzenie cykliczne (i wszystkie jego instancje) lub tylko na poszczególne instancje. Instancje, które różnią się od nadrzędnego wydarzenia cyklicznego, są nazywane wyjątkami.

Na przykład wyjątek może mieć inne podsumowanie, inną godzinę rozpoczęcia lub dodatkowych uczestników zaproszonych tylko na to wystąpienie. Możesz też całkowicie anulować instancję bez usuwania wydarzenia cyklicznego (anulowanie instancji jest odzwierciedlane w status status wydarzenia).

Przykłady pracy z wydarzeniami cyklicznymi i instancjami za pomocą interfejsu Google Calendar API znajdziesz w sekcji Wydarzenia cykliczne.

Strefy czasowe

Strefa czasowa określa region, w którym obowiązuje jednolity czas standardowy. W interfejsie Google Calendar API strefy czasowe określa się za pomocą identyfikatorów stref czasowych IANA.

Strefę czasową możesz ustawić zarówno dla kalendarzy, jak i wydarzeń. W sekcjach poniżej opisujemy skutki tych ustawień.

Strefa czasowa kalendarza

Strefa czasowa kalendarza jest też nazywana domyślną strefą czasową ze względu na jej wpływ na wyniki zapytań. Strefa czasowa kalendarza wpływa na sposób interpretowania lub prezentowania wartości czasu przez metody events.get(), events.list() i events.instances().

Konwersja strefy czasowej w wynikach zapytania

Wyniki metod get(), list() i instances() są zwracane w strefie czasowej określonej w parametrze timeZone. Jeśli pominiesz ten parametr, te metody będą domyślnie używać strefy czasowej kalendarza.

Dopasowywanie wydarzeń całodniowych do zapytań z przedziałem czasu

Metody list() i instances() umożliwiają określenie filtrów czasu rozpoczęcia i zakończenia, a metoda zwraca instancje, które mieszczą się w określonym zakresie. Strefa czasowa kalendarza służy do obliczania czasu rozpoczęcia i zakończenia wydarzeń całodniowych, aby określić, czy mieszczą się one w specyfikacji filtra.

Strefa czasowa wydarzenia

Instancje wydarzeń mają czas rozpoczęcia i zakończenia, a specyfikacja tych czasów może obejmować strefę czasową. Strefę czasową możesz określić na kilka sposobów. Wszystkie te sposoby określają ten sam czas:

• Dodaj przesunięcie strefy czasowej w polu dateTime, np. 2017-01-25T09:00:00-0500.
• Określ czas bez przesunięcia, np. 2017-01-25T09:00:00, pozostawiając pole timeZone puste (domyślnie używana jest strefa czasowa).
• Określ czas bez przesunięcia, np. 2017-01-25T09:00:00, ale użyj pola timeZone, aby określić strefę czasową.

Jeśli wolisz, możesz też określić czas wydarzenia w formacie UTC:

• Określ czas w formacie UTC: 2017-01-25T14:00:00Z lub użyj przesunięcia zerowego 2017-01-25T14:00:00+0000.

Wewnętrzna reprezentacja czasu wydarzenia jest taka sama we wszystkich tych przypadkach, ale ustawienie pola timeZone powoduje przypisanie strefy czasowej do wydarzenia, tak jak w przypadku ustawienia strefy czasowej wydarzenia w interfejsie Kalendarza UI:

W przypadku pojedynczych wydarzeń możesz określić różne strefy czasowe dla czasu rozpoczęcia i zakończenia wydarzenia. (Może to być przydatne w przypadku wydarzeń, takich jak podróże, które faktycznie rozpoczynają się i kończą w różnych strefach czasowych). W przypadku wydarzeń cyklicznych zapoznaj się z sekcją [Strefa czasowa wydarzenia cyklicznego](#recurring-event-time-zone).

Strefa czasowa wydarzenia cyklicznego

W przypadku wydarzeń cyklicznych musisz zawsze określić jedną strefę czasową, aby rozwinąć powtórzenia wydarzenia.