Kalendarze i wydarzenia

W tym przewodniku opisano kalendarze, wydarzenia i ich wzajemne powiązania.

Kalendarze

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

Wydarzenia

Zdarzenie to obiekt powiązany z określoną datą lub określonym zakresem czasowym. Zdarzenia są identyfikowane za pomocą unikalnego identyfikatora. Oprócz daty i godziny rozpoczęcia oraz zakończenia wydarzenia zawierają one inne dane, takie jak podsumowanie, opis, lokalizacja, stan, przypomnienia, załączniki itp.

Typy zdarzeń

Kalendarz Google obsługuje pojedyncze i cykliczne wydarzenia:

• Pojedyncze zdarzenie reprezentuje niepowtarzalne zdarzenie.
• Zdarzenie cykliczne definiuje wiele wystąpień.

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

• Zdarzenie w określonym czasie występuje między 2 określonymi punktami w czasie. Zdarzenia o zdefiniowanym czasie używają pól start.dateTime i end.dateTime do określania, kiedy mają wystąpić.
• Wydarzenie całodniowe obejmuje cały dzień lub serię kolejnych dni. Zdarzenia całodniowe używają pól start.date i end.date do określania, kiedy się zdarzają. Pamiętaj, że pole strefy czasowej nie ma znaczenia w przypadku zdarzeń całodniowych.

Początek i koniec wydarzenia muszą być określone czasowo lub oba muszą być całodniowe. Na przykład nie można podać wartości start.date i end.dateTime.

Organizatorzy

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

Ten diagram pokazuje relację koncepcyjną 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. Kalendarz ten jest tworzony automatycznie dla każdego nowego konta użytkownika, a jego identyfikator zwykle odpowiada podstawowemu adresowi e-mail użytkownika. Dopóki konto istnieje, użytkownik nie może usunąć głównego kalendarza ani przekazać go innej osobie. Możesz jednak nadal udostępniać go innym użytkownikom.

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

Kalendarz i lista kalendarzy

Kolekcja Kalendarze reprezentuje wszystkie istniejące kalendarze. Możesz go 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 są właściwościami globalnymi.

CalendarList to zbiór wszystkich wpisów w kalendarzu, które użytkownik dodał do swojej listy (wyświetlany w panelu po lewej stronie interfejsu internetowego). Możesz z niego korzystać, aby dodawać i usuwać istniejące kalendarze z listy użytkowników. Możesz też używać tej funkcji do pobierania i ustawiania wartości właściwości kalendarza dotyczących konkretnego użytkownika, takich jak domyślne przypomnienia. Innym przykładem jest kolor pierwszego planu, ponieważ różni użytkownicy mogą ustawić różne kolory dla tego samego kalendarza.

W tej tabeli porównano znaczenie operacji w przypadku 2 kolekcji:

Operacja	Kalendarze	CalendarList
insert	Tworzy nowy kalendarz pomocniczy. Domyślnie ten kalendarz jest również dodawany do listy kalendarzy twórcy.	Wstawia istniejący kalendarz na listę użytkownika.
delete	Usuwa kalendarz pomocniczy.	Usuwanie kalendarza z listy użytkownika.
get	Pobiera metadane kalendarza, np. tytuł czy strefę czasową.	Pobiera metadane oraz dostosowywanie według użytkownika, na przykład kolory lub przypomnienia.
patch/update	Modyfikuje metadane kalendarza.	Modyfikuje właściwości kalendarza dla poszczególnych użytkowników.

Wydarzenia cykliczne

Niektóre wydarzenia mają regularny harmonogram, np. cotygodniowe spotkania, urodziny czy święta. Oprócz różnych czasów rozpoczęcia i zakończenia te powtarzające się zdarzenia są często identyczne.

Zdarzenia nazywamy 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:

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

• pole powtarzania (określa, jak często ma się powtarzać zdarzenie);

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

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

• FREQ – częstotliwość, z jaką zdarzenie ma się powtarzać (np. DAILY lub WEEKLY). Wartość wymagana.

• INTERVAL – działa razem z opcją FREQ i określa, jak często ma być powtarzane zdarzenie. Na przykład FREQ=DAILY;INTERVAL=2 oznacza raz na 2 dni.

• COUNT – liczba powtórzeń wydarzenia.

  Aby określić koniec powtarzania zdarzenia, możesz użyć funkcji LICZBA lub DO. Nie używaj obu w tej samej regule.

• UNTIL – data lub data i godzina, do których ma być powtarzane zdarzenie (włącznie).

• BYDAY – dni tygodnia, w których ma się powtarzać wydarzenie (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ą wystąpić zdarzenia. Na przykład: RDATE;VALUE=DATE:19970101,19970120. Użyj tego, aby dodać dodatkowe wystąpienia, które nie są objęte RRULE.

Właściwość EXDATE jest podobna do RDATE, ale określa daty lub daty i godziny, kiedy zdarzenie nie powinno wystąpić. Oznacza to, że te wystąpienia powinny zostać wykluczone. Musi wskazywać prawidłową instancję wygenerowaną przez regułę powtarzania.

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

Każda z nich może występować w polu powtarzania wiele razy. Powtarzanie jest zdefiniowane jako suma wszystkich reguł RRULE i RDATE z wyłączeniem tych wykluczonych przez wszystkie reguły EXDATE.

Oto kilka przykładów zdarzeń okresowych:

1. Wydarzenie, które występuje od 6:00 do 7:00 rano każdego wtorku i piątek, począwszy od 15 września 2015 r. i zakończone po 5 wystąpieniu 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. Całodniowe wydarzenie, które rozpoczyna się 1 czerwca 2015 r. i powtarza 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

Cykliczny event składa się z kilku wystąpień: poszczególnych wystąpień w różnych momentach. Te instancje działają jak zdarzenia.

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

Na przykład wyjątek może mieć inne podsumowanie, inny czas rozpoczęcia lub dodatkowych uczestników zaproszonych tylko na tę sesję. Możesz też anulować instancję bez usuwania wydarzenia cyklicznego (anulowania instancji są odzwierciedlane w wydarzeniu status).

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

Strefy czasowe

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

Możesz ustawić strefę czasową 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 i prezentowania wartości czasowych przez metody events.get(), events.list() i events.instances().

Przeliczanie wyników zapytania na inną strefę czasową

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

Dopasowywanie zdarzeń całodniowych do zapytań z ramkami czasowymi

Metody list() i instances() umożliwiają określenie filtrów czasu rozpoczęcia i zakończenia, tak by metoda zwracała instancje należące do określonego zakresu. Strefa czasowa kalendarza służy do obliczania godzin rozpoczęcia i zakończenia wydarzeń całodniowych w celu określenia, czy mieszczą się one w ramach specyfikacji filtra.

Strefa czasowa wydarzenia

Instancje zdarzeń mają czas rozpoczęcia i zakończenia, a specyfikacja tych godzin może zawierać strefę czasową. Strefę czasową możesz określić na kilka sposobów, z których każdy określa tę samą godzinę:

• W polu dateTime uwzględnij przesunięcie strefy czasowej, np. 2017-01-25T09:00:00-0500.
• Określ czas bez przesunięcia, np. 2017-01-25T09:00:00, pozostawiając pole timeZone puste (w tym przypadku zostanie użyta domyślna 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ż podać godziny wydarzeń w strefie czasowej UTC:

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

We wszystkich tych przypadkach wewnętrzna reprezentacja czasu wydarzenia jest taka sama, ale ustawienie pola timeZone powoduje przypisanie do wydarzenia strefy czasowej, tak jak w przypadku ustawienia strefy czasowej wydarzenia za pomocą interfejsu użytkownika Kalendarza:

W przypadku pojedynczych wydarzeń możesz określić różne strefy czasowe dla godzin rozpoczęcia i zakończenia. (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). Informacje o wydarżaniach cyklicznych znajdziesz poniżej.

Strefa czasowa wydarzenia cyklicznego

W przypadku wydarzeń cyklicznych musisz zawsze określić jedną strefę czasową. Jest on potrzebny do rozszerzenia powtórzeń zdarzenia.