W tym przewodniku opisujemy kalendarze, wydarzenia i 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 za pomocą identyfikatora, który jest adresem e-mail. Kalendarze mogą mieć wielu właścicieli.
Wydarzenia
Wydarzenie to obiekt powiązany z określoną datą lub zakresem dat. Zdarzenia są identyfikowane za pomocą unikalnego identyfikatora. Oprócz daty i godziny rozpoczęcia oraz zakończenia wydarzenia zawierają inne dane, takie jak podsumowanie, opis, lokalizacja, stan, przypomnienia, załączniki itp.
Typy zdarzeń
Kalendarz Google obsługuje wydarzenia pojedyncze i cykliczne:
- Pojedyncze zdarzenie reprezentuje niepowtarzalne wystąpienie.
- Wydarzenie cykliczne określa wiele wystąpień.
Wydarzenia mogą być też czasowe lub całodniowe:
- Zdarzenie ograniczone czasowo występuje między dwoma określonymi punktami w czasie. Zdarzenia czasowe używają pól
start.dateTimeiend.dateTimedo określania, kiedy mają wystąpić. - Wydarzenie całodniowe trwa cały dzień lub kilka kolejnych dni. W przypadku wydarzeń całodniowych do określania czasu ich trwania używa się pól
start.dateiend.date. 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 główny kalendarz zaproszonego użytkownika.
Poniższy diagram przedstawia koncepcyjną relację między kalendarzami, wydarzeniami i innymi powiązanymi elementami:
Kalendarze główne i inne kalendarze
Kalendarz główny to specjalny rodzaj 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 głównego kalendarza 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 utworzyć dowolną liczbę innych kalendarzy. Możesz 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ż pobierać i 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 to właściwości globalne.
CalendarList to zbiór wszystkich wpisów w kalendarzu, które użytkownik dodał do swojej listy (wyświetlanej w panelu po lewej stronie interfejsu internetowego). Możesz go używać do dodawania i usuwania istniejących kalendarzy z listy użytkowników. Możesz też używać go do pobierania i ustawiania wartości właściwości kalendarza 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ównano znaczenie operacji w przypadku obu kolekcji:
| 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ł i strefę czasową. | Pobiera metadane oraz dostosowania specyficzne dla użytkownika, takie jak kolor czy zastąpienie przypomnień. |
patch/update |
Modyfikuje metadane kalendarza. | Modyfikuje właściwości kalendarza dotyczące konkretnego użytkownika. |
Wydarzenia cykliczne
Niektóre wydarzenia odbywają 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. Wydarzenia pojedyncze nie są cykliczne i odbywają się tylko raz.
Reguła powtarzania
Harmonogram wydarzenia cyklicznego jest określany w 2 częściach:
pola rozpoczęcia i zakończenia (które określają pierwsze wystąpienie, tak jakby było to pojedyncze wydarzenie),
pole powtarzania (które określa, jak wydarzenie powinno się powtarzać w czasie);
Pole powtarzania zawiera tablicę ciągów znaków reprezentujących jedną lub kilka właściwości RRULE, RDATE lub EXDATE zdefiniowanych w RFC 5545.
Właściwość RRULE jest najważniejsza, ponieważ definiuje regularną regułę powtarzania zdarzenia. Składa się z kilku komponentów. Oto niektóre z nich:
FREQ– częstotliwość powtarzania wydarzenia (np.DAILYlubWEEKLY). Wymagany.INTERVAL– współdziała z parametremFREQ, aby określić, jak często wydarzenie ma być powtarzane. Na przykładFREQ=DAILY;INTERVAL=2oznacza raz na 2 dni.COUNT– liczba powtórzeń tego zdarzenia.UNTIL– data lub data i godzina, do której wydarzenie powinno być powtarzane (włącznie).BYDAY– dni tygodnia, w których ma się powtarzać wydarzenie (SU,MO,TUitp.). Inne podobne komponenty toBYMONTH,BYYEARDAYiBYHOUR.
Właściwość RDATE określa dodatkowe daty lub daty i godziny, w których powinny wystąpić zdarzenia. Na przykład: RDATE;VALUE=DATE:19970101,19970120.
Użyj tej opcji, 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, w których wydarzenie nie powinno się odbyć. Oznacza to, że takie wystąpienia powinny być wykluczone. Musi to być prawidłowa instancja wygenerowana przez regułę cykliczną.
EXDATE i RDATE mogą mieć strefę czasową i muszą być datami (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.
Cykliczność jest definiowana jako suma wszystkich reguł RRULE i RDATE pomniejszona o reguły wykluczone przez wszystkie reguły EXDATE.
Oto kilka przykładów wydarzeń cyklicznych:
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 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" ], …Wydarzenie całodniowe rozpoczynające się 1 czerwca 2015 r. i powtarzające się co 3 dni przez cały miesiąc, z wyjątkiem 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 wystąpień, czyli konkretnych zdarzeń, które mają miejsce w różnym czasie. Te instancje działają jak zdarzenia.
Modyfikacje wydarzenia cyklicznego mogą dotyczyć całego wydarzenia cyklicznego (i wszystkich jego wystąpień) lub tylko poszczególnych wystąpień. Wystąpienia, które różnią się od nadrzędnego wydarzenia cyklicznego, są nazywane wyjątkami.
Wyjątek może mieć na przykład inny opis, 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 odzwierciedlone w wydarzeniu status).
Przykłady pracy z wydarzeniami cyklicznymi i ich 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śla się za pomocą identyfikatorów stref czasowych IANA.
Możesz ustawić strefę czasową 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 interpretacji lub prezentacji wartości czasu przez metody events.get(), events.list() i events.instances().
- Konwersja strefy czasowej wyniku zapytania
- Wyniki metod
get(),list()iinstances()są zwracane w strefie czasowej określonej w parametrzetimeZone. Jeśli pominiesz ten parametr, wszystkie te metody będą domyślnie używać strefy czasowej kalendarza. - Dopasowywanie wydarzeń całodniowych do zapytań z określonym przedziałem czasu
- Metody
list()iinstances()umożliwiają określanie 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 godzin rozpoczęcia i zakończenia wydarzeń całodniowych, aby określić, czy mieszczą się one w specyfikacji filtra.
Strefa czasowa wydarzenia
Wystąpienia wydarzeń mają godzinę rozpoczęcia i zakończenia. Specyfikacja tych godzin może obejmować strefę czasową. Strefę czasową możesz określić na kilka sposobów. Wszystkie poniższe przykłady oznaczają ten sam czas:
- Wpisz przesunięcie strefy czasowej w polu
dateTime, na przykład2017-01-25T09:00:00-0500. - Określ czas bez przesunięcia, np.
2017-01-25T09:00:00, pozostawiając poletimeZonepuste (domyślnie używana jest strefa czasowa). - Określ czas bez przesunięcia, np.
2017-01-25T09:00:00, ale użyj polatimeZone, aby określić strefę czasową.
Możesz też określić godziny wydarzeń w strefie czasowej UTC:
- Określ czas w strefie czasowej UTC:
2017-01-25T14:00:00Zlub użyj przesunięcia zerowego2017-01-25T14:00:00+0000.
Wewnętrzna reprezentacja czasu wydarzenia jest we wszystkich tych przypadkach taka sama, ale ustawienie pola timeZone powoduje dołączenie strefy czasowej do wydarzenia, tak jak w przypadku ustawienia strefy czasowej wydarzenia w interfejsie Kalendarza:
Strefa czasowa wydarzenia cyklicznego
W przypadku wydarzeń cyklicznych zawsze należy podać jedną strefę czasową. Jest to konieczne, aby rozwinąć powtórzenia wydarzenia.