Kalendarze i wydarzenia

Ten przewodnik opisuje kalendarze, wydarzenia i ich wzajemne relacje.

Kalendarze

A calendar is a collection of related events, along with additional metadata such as summary, default time zone, location, etc. Each calendar is identified by an ID, which is an email address. Kalendarze można udostępniać innym osobom. Kalendarze główne należą do powiązanych z nimi kont użytkowników, 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, załączniki itp.

Typy zdarzeń

Kalendarz Google obsługuje pojedyncze i cykliczne wydarzenia:

  • Pojedyncze wydarzenie reprezentuje unikalne wystąpienie.
  • Cykliczne wydarzenie definiuje wiele wystąpień.

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

  • Czasowe wydarzenie trwa między 2 określonymi punktami w czasie. Wydarzenia czasowe używają pól start.dateTime i end.dateTime do określania, kiedy mają się odbyć.
  • Całodniowe wydarzenie 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.

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 podstawowemu adresowi e-mail użytkownika. Dopóki konto istnieje, jego 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 też 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.

Kalendarz i lista kalendarzy

Kolekcja Calendars (Kalendarze) reprezentuje wszystkie istniejące kalendarze. Można jej używać do tworzenia i usuwania kalendarzy. Możesz też pobierać i ustawiać właściwości globalne udostępniane wszystkim użytkownikom mającym dostęp do kalendarza. Tytuł kalendarza i domyślna strefa czasowa to np. właściwości globalne.

CalendarList (Lista kalendarzy) to zbiór wszystkich wpisów kalendarza, 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żytkowników. 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.

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ą cykliczne , jeśli powtarzają się zgodnie z określonym harmonogramem. Pojedyncze wydarzenia nie powtarzają się 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),

  • 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ść, z jaką wydarzenie ma się powtarzać (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.

  • 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 właściwości, 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 ona 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 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:

    ...
"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, czyli jego konkretnych wystąpień w różnych terminach. 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, nazywane są wyjątkami.

Wyjątek może mieć np. 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 polu `status` wydarzenia).status

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

Strefy czasowe

Strefa czasowa określa region, w którym obowiązuje jednolity czas standardowy. W interfejsie Kalendarza Google 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 wpływ 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 jest używana 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 UTC:

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

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

Fragment zrzutu ekranu przedstawiający strefę czasową wydarzenia

Strefa czasowa wydarzenia cyklicznego

W przypadku wydarzeń cyklicznych zawsze trzeba określić jedną strefę czasową. Jest ona potrzebna do rozszerzenia powtórzeń wydarzenia.