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 itd. Każdy kalendarz ma identyfikator, który jest adresem e-mail. Kalendarze mogą mieć kilku właścicieli.
Wydarzenia
Zdarzenie to obiekt powiązany z określonym zakresem dat lub godzin. Zdarzenia są określane na podstawie unikalnego identyfikatora. Oprócz daty i godziny rozpoczęcia oraz zakończenia wydarzenia zawierają też inne dane, takie jak podsumowanie, opis, lokalizacja, stan, przypomnienia, załączniki itp.
Typy zdarzeń
Kalendarz Google obsługuje wydarzenia jedno i cykliczne:
- Pojedyncze zdarzenie reprezentuje unikalne wystąpienie.
- Zdarzenie cykliczne definiuje wiele wystąpień.
Wydarzenia mogą być też rozłożone w czasie lub całodniowe:
- Zdarzenie w określonym czasie występuje między 2 określonymi punktami w czasie. Zdarzenia czasowe do określenia czasu wystąpienia wykorzystują pola
start.dateTime
iend.dateTime
. - Wydarzenie całodniowe obejmuje cały dzień lub serię dni. Zdarzenia całodniowe określają, kiedy występują, za pomocą pól
start.date
iend.date
. Pamiętaj, że pole strefy czasowej nie ma znaczenia dla wydarzeń całodniowych.
Organizatorzy
Wydarzenia mają jeden organizator, czyli kalendarz zawierający główną kopię wydarzenia. Wydarzenia mogą mieć wielu uczestników. Uczestnik jest zwykle głównym kalendarzem zaproszonego użytkownika.
Poniższy diagram przedstawia koncepcyjną relację 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. Ten kalendarz jest tworzony automatycznie dla każdego nowego konta użytkownika, a jego identyfikator zwykle jest zgodny z podstawowym adresem e-mail użytkownika. Dopóki konto istnieje, jego kalendarz główny nigdy nie może zostać usunięty ani nie należy do użytkownika. Nadal można ją jednak udostępniać innym użytkownikom.
Oprócz kalendarza głównego możesz utworzyć dowolną liczbę innych kalendarzy. Kalendarze te można 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ż pobierać lub ustawiać właściwości globalne udostępniane wszystkim użytkownikom z dostępem 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 (są one widoczne w panelu po lewej stronie interfejsu internetowego). Za pomocą tego interfejsu możesz dodawać do listy użytkowników i usuwać istniejące kalendarze. Służy on również 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ą ustawić różne kolory dla tego samego kalendarza.
W poniższej tabeli porównano znaczenie operacji w przypadku obu zbiorów:
Operacja | Kalendarze | CalendarList |
---|---|---|
insert |
Tworzy nowy kalendarz pomocniczy. Domyślnie ten 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ł czy strefę czasową. | Pobiera metadane oraz dostosowywanie według użytkownika, takie jak kolory lub przypomnienia o zastąpieniu. |
patch /update |
Modyfikuje metadane kalendarza. | Modyfikuje właściwości kalendarza specyficzne dla użytkownika. |
Wydarzenia cykliczne
Niektóre wydarzenia występują w regularnych odstępach czasu, np. cotygodniowe spotkania, urodziny i święta. Oprócz różnych czasów 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 mają miejsce tylko raz.
Reguła powtarzania
Harmonogram wydarzenia cyklicznego jest zdefiniowany w dwóch częściach:
jego pola rozpoczęcia i zakończenia (określające pierwsze wystąpienie, jakby było to tylko samodzielne zdarzenie), a także
jego pole powtarzania (określające, jak zdarzenie powinno być powtarzane w czasie).
Pole powtarzania zawiera tablicę ciągów znaków reprezentujących 1 lub kilka właściwości RRULE
, RDATE
lub EXDATE
, zgodnie z definicją w RFC 5545.
Właściwość RRULE
jest najważniejsza, ponieważ definiuje zwykłą regułę powtarzania zdarzenia. Składa się z kilku elementów. Oto niektóre z nich:
FREQ
– częstotliwość, z jaką zdarzenie ma się powtarzać (np.DAILY
lubWEEKLY
). Wymagana.INTERVAL
– współpracuje z parametremFREQ
, aby określić, jak często wydarzenie ma się powtarzać. np.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
itp.). Inne podobne komponenty toBYMONTH
,BYYEARDAY
iBYHOUR
.
Właściwość RDATE
określa dodatkowe daty lub daty i godziny, kiedy powinny wystąpić zdarzenia. 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 daty i godziny, kiedy zdarzenie nie powinno wystąpić. Oznacza to, że należy je wykluczyć. Musi wskazywać prawidłową instancję wygenerowaną przez regułę powtarzania.
EXDATE
i RDATE
mogą mieć strefę czasową i w przypadku wydarzeń całodniowych muszą być datami (a nie datami i godzinami).
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 powtarzających się wydarzeń:
Zdarzenie, które rozpoczyna się od 6:00 do 7:00 w każdy wtorek i piątek od 15 września 2015 r., a kończy 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" ], …
Wydarzenie całodniowe rozpoczynające się 1 czerwca 2015 r. i powtarzające się co 3 dni w ciągu miesiąca, z wyjątkiem 10 czerwca, ale także z 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ń: jego konkretnych wystąpień w różnym czasie. Te instancje same działają jako zdarzenia.
Powtarzające się modyfikacje zdarzenia mogą wpływać na całe zdarzenie cykliczne (i wszystkie jego instancje) lub tylko na poszczególne instancje. Wystąpienia różniące 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 dodatkowi uczestnicy zaproszeni tylko do tej instancji. Możesz też całkowicie anulować wystąpienie bez usuwania wydarzenia cyklicznego (anulowanie instancji jest odzwierciedlone w zdarzeniu status
).
Przykłady korzystania z wydarzeń i wystąpień cyklicznych 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 możesz określić strefy czasowe za pomocą identyfikatorów strefy czasowej IANA.
Możesz ustawić strefę czasową zarówno dla kalendarzy, jak i wydarzeń. Wpływ tych ustawień znajdziesz w kolejnych sekcjach.
Strefa czasowa kalendarza
Strefa czasowa kalendarza jest też nazywana domyślną strefą czasową ze względu na wpływ tej strefy na wyniki zapytań. Strefa czasowa kalendarza wpływa na sposób interpretowania lub przedstawiania wartości czasowych przez metody events.get()
, events.list()
i events.instances()
.
- Konwersja według strefy czasowej wyniku zapytania
- Wyniki metod
get()
,list()
iinstances()
są zwracane w strefie czasowej podanej w parametrzetimeZone
. Jeśli pominiesz ten parametr, we wszystkich tych metodach domyślnie używana będzie strefa czasowa kalendarza. - Dopasowywanie wydarzeń całodniowych do zapytań ograniczonych czasowo
- Metody
list()
iinstances()
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 czasu rozpoczęcia i zakończenia wydarzeń całodniowych w celu określenia, czy spełniają one wymagania 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
podaj 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 poletimeZone
puste (domyślnie używana jest tu strefa czasowa). - Podaj godzinę bez przesunięcia, np.
2017-01-25T09:00:00
, ale do określenia strefy czasowej użyj polatimeZone
.
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żyj2017-01-25T14:00:00+0000
przesunięcia o zerowej wartości.
Wewnętrzna reprezentacja czasu wydarzenia jest we wszystkich tych przypadkach taka sama, ale ustawienie pola timeZone
powoduje przypisanie do wydarzenia strefy czasowej, tak jak podczas ustawiania strefy czasowej wydarzenia w interfejsie Kalendarza:
Strefa czasowa wydarzenia cyklicznego
W przypadku wydarzeń cyklicznych musisz zawsze określić jedną strefę czasową. Jest to konieczne, aby zwiększyć liczbę powtórzeń wydarzenia.