Kalendarze i wydarzenia

Stay organized with collections Save and categorize content based on your preferences.

Ten przewodnik opisuje kalendarze, wydarzenia i ich relacje między sobą.

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 określany na podstawie identyfikatora, który jest adresem e-mail. Kalendarze mogą mieć wielu właścicieli.

Zdarzenia

Zdarzenie to obiekt powiązany z określoną datą lub zakresem czasu. Wydarzenia są rozpoznawane na podstawie unikalnego identyfikatora w kalendarzu. Oprócz daty i godziny rozpoczęcia 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 to unikalne wystąpienie.
  • Zdarzenie cykliczne definiuje wiele wystąpień.

Wydarzenia mogą być też planowane lub całodobowe:

  • Zdarzenie czasowe ma miejsce między dwoma określonymi punktami w czasie. Zdarzenia czasowe używają pól start.dateTime i end.dateTime, aby określić, kiedy nastąpi.
  • Wydarzenie całodniowe obejmuje cały dzień lub ciąg kolejnych dni. Wydarzenia całodniowe można określić za pomocą pól start.date i end.date. Pamiętaj, że pole strefy czasowej nie ma wpływu na wydarzenia całodniowe.

Organizatorzy

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

Poniższy diagram przedstawia zależność 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 jest tworzony automatycznie dla każdego nowego konta użytkownika, a jego identyfikator zwykle odpowiada głównemu adresowi e-mail użytkownika. Jeśli konto istnieje, jego główny kalendarz nigdy nie może zostać usunięty przez użytkownika ani stać się jego własnością. Można ją jednak udostępniać innym użytkownikom.

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

Kalendarz i lista kalendarzy

Kolekcja Kalendarze reprezentuje wszystkie istniejące kalendarze. Za jego pomocą można tworzyć i usuwać kalendarze. Możesz też pobierać i ustawiać właściwości globalne udostępnione wszystkim użytkownikom z dostępem do kalendarza. Na przykład tytuł kalendarza i domyślna strefa czasowa to usługi globalne.

CalendarList to zbiór wszystkich pozycji kalendarza, które użytkownik dodał do swojej listy (wyświetlane w panelu po lewej stronie interfejsu internetowego). Za jego pomocą można dodawać i usuwać istniejące kalendarze do/z listy użytkowników. W ten sposób możesz też pobierać i ustawiać wartości właściwości kalendarza specyficznych dla użytkownika, np. domyślnych przypomnień. Innym przykładem jest kolor pierwszego planu, ponieważ różne osoby mogą mieć w tym samym kalendarzu ustawione różne kolory.

W tabeli poniżej przedstawiono znaczenie operacji w 2 kolekcjach:

Operacja Kalendarze ListaKalendarz
insert Tworzy nowy kalendarz pomocniczy. Domyślnie ten kalendarz jest też dodawany do listy kalendarzy twórcy. Wstawia istniejący kalendarz do listy użytkowników.
delete Usuwa kalendarz pomocniczy. Usuwa kalendarz z listy użytkownika.
get Pobiera metadane kalendarza, np. tytuł, strefę czasową. Pobiera metadane oraz dostosowania dostosowane do użytkowników, takie jak kolory czy zastąpienia.
patch/update Zmienia metadane kalendarza. Zmienia właściwości kalendarza przypisane do użytkownika.

Wydarzenia cykliczne

Niektóre wydarzenia występują wiele razy, np. cotygodniowe spotkania, urodziny i święta. Różne wydarzenia często mają identyczne czasy rozpoczęcia i zakończenia, poza tymi, których czas się kończy.

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

Reguła powtarzania

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

  • jego pola rozpoczęcia i zakończenia (określające pierwsze wystąpienie, jakby było to samodzielne wydarzenie);

  • Pole powtarzania (określające sposób powtarzania zdarzenia).

Pole powtarzania zawiera tablicę reprezentującą co najmniej jedną właściwość RRULE, RDATE lub EXDATE, zgodnie z definicją w dokumencie RFC 5545.

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

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

  • INTERVAL – współpracuje z właściwością 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,

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

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

Właściwość RDATE określa dodatkowe daty lub daty i godziny wystąpienia zdarzeń. Na przykład: RDATE;VALUE=DATE:19970101,19970120. Służy do dodawania kolejnych 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 powinno mieć miejsca. Oznacza to, że te zdarzenia powinny być wykluczone. Musi on wskazywać prawidłową instancję wygenerowaną przez regułę powtarzania.

EXDATE i RDATE mogą mieć strefę czasową i powinny być datą (a nie datą) dla wydarzeń całodniowych.

Każda z nich może wystąpić w polu powtarzania wielokrotnie. Powtarzanie jest określane jako połączenie wszystkich reguł RRULE i RDATE pomniejszonej o reguły wykluczone przez wszystkie reguły EXDATE.

Oto kilka przykładów wydarzeń cyklicznych:

  1. Wydarzenie trwające od 6:00 do 7:00 w każdy wtorek i piątek, począwszy od 15 września 2015 roku i kończące się po piątym 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. Wydarzenie całodniowe rozpoczyna się 1 czerwca 2015 r. i powtarza się co 3 dni, z wyjątkiem 10 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

Zdarzenie cykliczne składa się z kilku wystąpień: konkretne wystąpienia w różnych momentach. Te instancje działają jak wydarzenia.

Modyfikacje wydarzeń cyklicznych 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, inny czas rozpoczęcia lub dodatkowy uczestnicy zaproszeni tylko do tej instancji. Możesz też całkowicie anulować instancję bez usuwania wydarzenia cyklicznego (anulowania instancji są odzwierciedlane w zdarzeniu status).

Przykłady obsługi wydarzeń cyklicznych i instancji za pomocą interfejsu Calendar API znajdziesz tutaj.

Strefy czasowe

Strefa czasowa określa region, który stosuje jednolity czas standardowy. W interfejsie Calendar API możesz określić strefy czasowe za pomocą identyfikatorów IANA strefy czasowej.

Możesz ustawić strefę czasową zarówno w kalendarzach, jak i wydarzeniach. Skutki tych ustawień znajdziesz w sekcjach poniżej.

Strefa czasowa kalendarza

Strefa czasowa kalendarza jest też nazywana domyślną strefą czasową, ponieważ ma to wpływ na wyniki zapytań. Strefa czasowa kalendarza wpływa na sposób, w jaki wartości są interpretowane lub przedstawiane za pomocą metod events.get(), events.list() i events.instances().

Konwersja strefy czasowej wyniku zapytania
Wyniki metody get(), list() i instances() są zwracane w strefie czasowej określonej 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ń w wyznaczonych przedziałach czasu
Metody list() i instances() pozwalają określić filtry czasu rozpoczęcia i zakończenia, przy czym metoda zwracająca instancje mieści się w określonym zakresie. Strefa czasowa kalendarza służy do obliczania czasu rozpoczęcia i zakończenia wydarzeń całodniowych w celu określenia, czy należą one do specyfikacji filtra.

Strefa czasowa wydarzenia

Instancje zdarzeń mają godzinę rozpoczęcia i zakończenia, więc specyfikacja tych godzin może zawierać strefę czasową. Strefę czasową można określić na kilka sposobów:

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

Możesz też określić godziny wydarzeń w strefie czasowej UTC:

  • Podaj czas UTC: 2017-01-25T14:00:00Z lub użyj opóźnienia zerowego 2017-01-25T14:00:00+0000.

Wewnętrzna reprezentacja godziny wydarzenia jest taka sama w każdym z tych przypadków, ale ustawienie pola timeZone dołącza strefę do wydarzenia tak samo jak w przypadku ustawiania strefy czasowej za pomocą interfejsu Kalendarza:

Fragment ekranu przedstawiający strefę czasową wydarzenia

Strefa czasowa wydarzenia cyklicznego

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