Kalendarze i wydarzenia

W tym przewodniku opisano kalendarze, wydarzenia oraz ich wzajemne relacje.

Kalendarze

Kalendarz to zbiór powiązanych wydarzeń wraz z dodatkowymi metadanymi, takimi jak podsumowanie, domyślna strefa czasowa, lokalizacja itp. Każdy kalendarz jest identyfikowany przez identyfikator, który jest adresem e-mail. Kalendarze mogą mieć kilku właścicieli.

Wydarzenia

Zdarzenie to obiekt powiązany z konkretnym zakresem dat lub godzin. Zdarzenia mają unikalny identyfikator. Oprócz daty i godziny rozpoczęcia i zakończenia wydarzenia zawierają też inne dane, takie jak podsumowanie, opis, lokalizacja, stan, przypomnienia, załączniki itp.

Typy zdarzeń

Kalendarz Google obsługuje wydarzenia pojedyncze i cykliczne:

  • Pojedyncze zdarzenie oznacza unikalne wystąpienie.
  • Zdarzenie cykliczne definiuje wiele wystąpień.

Wydarzenia mogą też być ograniczone czasowo lub cały dzień:

  • Zdarzenie ograniczone czasowo zachodzi między 2 określonymi punktami w czasie. Zdarzenia objęte pomiarem czasu służą do określenia czasu wystąpienia zdarzeń za pomocą pól start.dateTime i end.dateTime.
  • Wydarzenie całodniowe obejmuje cały dzień lub serię dni. Zdarzenia całodniowe używają pól start.date i end.date, aby określić, kiedy występują. Pamiętaj, że pole strefy czasowej nie ma znaczenia w przypadku wydarzeń całodniowych.

Organizatorzy

Wydarzenia mają jeden organizator, czyli kalendarz zawierający główną kopię wydarzenia. W wydarzeniach może też brać udział wielu uczestników. Uczestnikem jest zwykle główny kalendarz zaproszonego użytkownika.

Poniższy diagram przedstawia relację pojęciową między kalendarzami, wydarzeniami i innymi powiązanymi elementami:

Kalendarze główne i inne

Kalendarz główny to specjalny typ kalendarza powiązany z jednym kontem użytkownika. Kalendarz jest tworzony automatycznie dla każdego nowego konta użytkownika. Jego identyfikator jest zwykle zgodny z podstawowym adresem e-mail użytkownika. Dopóki konto istnieje, użytkownik nie może usunąć kalendarza głównego ani usunąć z niego własności. Można ją jednak udostępniać innym użytkownikom.

Oprócz kalendarza głównego możesz utworzyć dowolną liczbę innych kalendarzy, a także je modyfikować, usuwać i udostępniać wielu użytkownikom.

Kalendarz i lista kalendarzy

Kolekcja Kalendarze reprezentuje wszystkie istniejące kalendarze. Można go używać do tworzenia i usuwania kalendarzy. Możesz też pobrać lub ustawić właściwości globalne udostępnione wszystkim użytkownikom mającym 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 kalendarza, które użytkownik dodał do swojej listy (wyświetlanej w lewym panelu interfejsu internetowego). Można jej używać do dodawania istniejących kalendarzy do list użytkowników i ich usuwania. Służy on również do pobierania i ustawiania wartości właściwości kalendarza specyficznych dla użytkownika, takich jak przypomnienia domyślne. Kolejnym przykładem jest kolor pierwszego planu, ponieważ różni użytkownicy mogą ustawić różne kolory dla tego samego kalendarza.

Tabela poniżej zawiera porównanie znaczenia operacji w tych 2 zbiorach danych:

Operacja Kalendarze CalendarList
insert Tworzy nowy kalendarz pomocniczy. Domyślnie kalendarz jest też dodawany do listy kalendarzy twórcy. Wstawia istniejący kalendarz na listę użytkownika.
delete Usuwa kalendarz pomocniczy. Usuwa kalendarz z listy użytkownika.
get Pobiera metadane kalendarza, np. tytuł, strefę czasową. Pobiera metadane oraz dostosowywanie zależne od użytkownika, takie jak kolor czy przypomnienia o zastąpieniu.
patch/update Modyfikuje metadane kalendarza. Modyfikuje właściwości kalendarza właściwe dla użytkownika.

Wydarzenia cykliczne

Niektóre wydarzenia odbywają się wiele razy zgodnie ze stałym harmonogramem. Są to np. cotygodniowe spotkania, urodziny i święta. Poza tym, że mają różne czasy rozpoczęcia i zakończenia, te powtarzające się zdarzenia są często identyczne.

Wydarzenia są nazywane cyklicznymi, jeśli powtarzają się zgodnie z określonym harmonogramem. Pojedyncze wydarzenia nie są cykliczne i występują tylko raz.

Reguła powtarzania

Harmonogram wydarzenia cyklicznego składa się z 2 części:

  • jego pola początkowego i końcowego (które definiują pierwsze wystąpienie, tak jakby było to samodzielne, pojedyncze zdarzenie) oraz

  • jego pole powtarzania (określające sposób powtarzania zdarzenia w czasie).

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

Właściwość RRULE jest najważniejsza, ponieważ określa regularną regułę powtarzania zdarzenia. Składa się z kilku elementów. Oto niektóre z nich:

  • FREQ – częstotliwość, z jaką zdarzenie ma być powtarzane (np. DAILY lub WEEKLY). Wymagane.

  • INTERVAL – wspólnie z elementem FREQ określa, jak często zdarzenie ma być powtarzane. Na przykład FREQ=DAILY;INTERVAL=2 oznacza raz na 2 dni.

  • COUNT – liczba powtórzeń wydarzenia.

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

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

Właściwość RDATE określa dodatkowe daty i godziny, w których powinny występować zdarzenia. Na przykład: RDATE;VALUE=DATE:19970101,19970120. Umożliwia dodanie dodatkowych wystąpień, których nie obejmuje RRULE.

Właściwość EXDATE jest podobna do RDATE, ale określa daty lub godziny, w których zdarzenie nie ma wystąpić. Oznacza to, że takie wystąpienia należy wykluczyć. Musi on wskazywać prawidłową instancję wygenerowaną przez regułę powtarzania.

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

Każda z właściwości może wielokrotnie występować w polu powtarzania. Powtarzanie jest zdefiniowane jako połączenie wszystkich reguł RRULE i RDATE, pomniejszone o reguły wykluczone przez wszystkie reguły EXDATE.

Oto kilka przykładów powtarzających się wydarzeń:

  1. Wydarzenie, które odbywa się od 6:00 do 7:00 we wtorek i piątek od 15 września 2015 r. do piątego wystąpienia 29 września:

    ...
    "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, które rozpoczyna się 1 czerwca 2015 r. i powtarza się co 3 dni w całym miesiącu z wyjątkiem 10 czerwca, ale nie uwzględnia 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 wystąpień, czyli konkretnych wystąpień w różnych momentach. Te instancje same w sobie działają jako zdarzenia.

Modyfikacje zdarzenia cyklicznego mogą dotyczyć całego zdarzenia cyklicznego (i wszystkich jego wystąpień) lub tylko poszczególnych instancji. Instancje, które różnią się od nadrzędnego wydarzenia cyklicznego, są nazywane wyjątkami.

Wyjątkiem mogą być na przykład inne podsumowanie, inny czas rozpoczęcia lub dodatkowi uczestnicy zaproszone tylko w ramach tej instancji. Możesz też całkowicie anulować instancję bez usuwania zdarzenia cyklicznego (anulowanie wystąpienia jest odzwierciedlane w zdarzeniu status).

Przykłady działania z wydarzeniami i instancjami cyklicznymi za pomocą interfejsu Google Calendar API znajdziesz tutaj.

Strefy czasowe

Strefa czasowa określa region, w którym obserwowany jest jednolity czas standardowy. W interfejsie Google Calendar API możesz określać strefy czasowe za pomocą identyfikatorów IANA stref czasowych.

Możesz ustawić strefę czasową zarówno dla kalendarzy, jak i wydarzeń. Efekty tych ustawień znajdziesz w sekcjach poniżej.

Strefa czasowa kalendarza

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

Konwersja według strefy czasowej wyniku zapytania
Wyniki metod get(), list() i instances() są zwracane w strefie czasowej podanej w parametrze timeZone. Jeśli pominiesz ten parametr, wszystkie te metody będą domyślnie używać strefy czasowej kalendarza.
Dopasowywanie wydarzeń całodniowych do zapytań z ograniczeniem czasowym
Metody list() i instances() pozwalają określać filtry czasu rozpoczęcia i zakończenia przy użyciu metod zwracających instancje, które mieszczą się w określonym zakresie. Strefa czasowa kalendarza służy do obliczania godzin rozpoczęcia i zakończenia wydarzeń całodniowych w celu określenia, czy pasują one do specyfikacji filtra.

Strefa czasowa wydarzenia

Instancje zdarzeń mają czas rozpoczęcia i zakończenia. Specyfikacja tych godzin może zawierać strefę czasową. Strefę czasową możesz określić na kilka sposobów. Wszystkie z nich określają tę samą godzinę:

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

Jeśli wolisz, możesz też podać godziny wydarzeń w strefie czasowej UTC:

  • Podaj godzinę w strefie czasowej UTC: 2017-01-25T14:00:00Z lub użyj przesunięcia zero w wysokości 2017-01-25T14:00:00+0000.

Wewnętrzna reprezentacja czasu wydarzenia jest we wszystkich tych przypadkach taka sama, ale ustawienie pola timeZone powoduje dodanie do wydarzenia strefy czasowej, podobnie jak ustawianie strefy czasowej wydarzenia w interfejsie Kalendarza:

Fragment zrzutu ekranu pokazujący strefę czasową wydarzenia

Strefa czasowa wydarzenia cyklicznego

W przypadku wydarzeń cyklicznych zawsze należy określić jedną strefę czasową. Jest to konieczne, aby zwiększyć liczbę powtórzeń wydarzenia.