W tym przewodniku opisano kalendarze, wydarzenia oraz ich wzajemne relacje.
Kalendarze
kalendarza, to zbiór powiązanych zdarzeń wraz z dodatkowymi metadanymi takich 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ć 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 wprowadzenia data i godzina zakończenia, zdarzenia zawierają 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ż dzielone w czasie lub całodniowe:
- Zdarzenie w określonym czasie występuje między 2 określonymi punktami w czasie. Wydarzenia czasowe
użyj pól
start.dateTime
iend.dateTime
, aby określić, kiedy wystąpienia. - Wydarzenie całodniowe obejmuje cały dzień lub serię dni. Całodzienne
za pomocą pól
start.date
iend.date
możesz określić, kiedy zdarzenia mają się pojawiać. 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ę zdarzenia. Zdarzenia mogą mieć wiele uczestników. Uczestnik jest zwykle głównym kalendarzem zaproszonego użytkownika.
Poniższy diagram przedstawia koncepcyjną relację między kalendarzami. zdarzenia i inne powiązane elementy:
Kalendarze główne inne kalendarze
Kalendarz główny to specjalny typ kalendarza powiązany z pojedynczym kalendarzem konto użytkownika. Ten kalendarz jest tworzony automatycznie dla każdego nowego konta użytkownika a jego identyfikator jest zwykle zgodny z podstawowym adresem e-mail użytkownika. Jeśli już istnieje konto, jego kalendarz główny nigdy nie może zostać usunięty lub użytkownik nie jest jego właścicielem przez użytkownika. Nadal można ją jednak udostępniać innym użytkownikom.
Oprócz kalendarza głównego możesz utworzyć dowolną liczbę innych kalendarzy; te kalendarze można modyfikować, usuwać i udostępniać między wieloma użytkownikami.
Kalendarz i lista kalendarzy
kolekcję Kalendarze, reprezentuje wszystkie istniejące kalendarze. Można go używać do tworzenia i usuwania kalendarze. Możesz też pobierać lub ustawiać właściwości globalne udostępniane w całej Użytkownicy mający dostęp do kalendarza. Na przykład tytuł i domyślne źródło w kalendarzu 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 (widoczne w lewym panelu interfejsu internetowego). Za pomocą tej usługi możesz dodawać i usuwać istniejące kalendarze z listy użytkowników. Służy on również do pobierania i ustawiania wartości właściwości kalendarza użytkownika, takich jak domyślne przypomnienia. Inny w przykładzie jest kolor pierwszego planu, ponieważ różni użytkownicy mogą mieć różne kolory ustawione 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ż dodany 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 strefa czasowa. | Pobiera metadane oraz dostosowywanie według użytkownika np. kolorem lub przypomnienia. |
patch /update |
Modyfikuje metadane kalendarza. | Modyfikuje właściwości kalendarza specyficzne dla użytkownika. |
Wydarzenia cykliczne
Niektóre wydarzenia występują wiele razy, tak jak w przypadku cotygodniowych spotkań, urodziny i święta. Oprócz czasu 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:
pola rozpoczęcia i zakończenia (określające pierwsze wystąpienie, tak jakby to pojedyncze, osobne wydarzenie),
jego pole powtarzania (określające, jak zdarzenie powinno być powtarzane w czasie).
Pole powtarzania zawiera tablicę ciągów reprezentujących co najmniej jeden
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łę dla
i powtórzyć wydarzenie. 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 ustawieniemFREQ
, aby określić częstotliwość zdarzenia. należy powtórzyć. Na przykładFREQ=DAILY;INTERVAL=2
oznacza raz na dwa 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 to m.in.BYMONTH
,BYYEARDAY
iBYHOUR
Właściwość RDATE
określa dodatkowe daty lub daty i godziny zdarzenia
powinny mieć miejsce. 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 to zdarzenie nie powinno wystąpić. Oznacza to, że te zdarzenia powinny być
wykluczono. Musi wskazywać prawidłową instancję wygenerowaną przez regułę powtarzania.
Pole EXDATE
i RDATE
mogą zawierać strefę czasową i muszą być datami (a nie datami i godzinami)
dla 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
, po odjęciu
te, które zostały wykluczone przez wszystkie reguły (EXDATE
).
Oto kilka przykładów powtarzających się wydarzeń:
Wydarzenie trwające od 6:00 do 7:00 we wtorek i w piątek od od 15 września 2015 r. i zakoń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" ], …
Całodniowe wydarzenie rozpoczynające się 1 czerwca 2015 r. i powtarzające się co 3 dni w ciągu miesiąca, z wyłączeniem 10 czerwca, ale także 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óżnych momentach. Te instancje same działają jako zdarzenia.
Powtarzające się modyfikacje zdarzeń mogą mieć wpływ na całość wydarzenie cykliczne (i wszystkie jego wystąpienia) lub tylko poszczególne wystąpienia. Wystąpienia różniące się od nadrzędnego wydarzenia cyklicznego są nazywane wyjątkami.
Wyjątek może mieć na przykład inne podsumowanie, inny czas rozpoczęcia,
lub dodatkowych uczestników zaproszonych tylko do tej instancji. Możesz też anulować
całkowicie bez usuwania wydarzenia cyklicznego
(anulowanie instancji jest odzwierciedlane w zdarzeniu
status
).
Przykłady pracy z wydarzeniami i wystąpieniami cyklicznymi za pomocą Interfejs Google Calendar API można znaleźć tutaj.
Strefy czasowe
Strefa czasowa określa region, w którym obowiązuje jednolity czas standardowy. W interfejsie Google Calendar API do określania strefy czasowej identyfikatory strefy czasowej IANA.
Możesz ustawić strefę czasową zarówno dla kalendarzy, jak i wydarzeń. W poniższych sekcjach i opisz ich skutki.
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
wartości czasowe są interpretowane lub przedstawiane przez
events.get()
events.list()
i
events.instances()
.
- Konwersja według strefy czasowej wyniku zapytania
- Wyniki
get()
,list()
orazinstances()
są zwracane w strefie czasowej podanej wtimeZone
. Jeśli pominiesz ten parametr, wszystkie te metody będą używać metody w wybranej strefie czasowej. - Dopasowywanie wydarzeń całodniowych do zapytań ograniczonych czasowo
-
list()
orazinstances()
pozwalają na określenie filtrów czasu rozpoczęcia i zakończenia, które zwracającym instancje, które należą do określonego zakresu. Strefa czasowa kalendarza jest używany do obliczania czasu rozpoczęcia i zakończenia całodniowych wydarzeń w celu określenia czy spełniają one specyfikację filtra.
Strefa czasowa wydarzenia
Instancje zdarzeń mają czas rozpoczęcia i zakończenia. specyfikacja tych czasów może zawierać strefę czasową. Strefę czasową można określić na kilka sposobów: następujące wszystkie określają ten sam czas:
- 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 godziny wydarzenia jest we wszystkich tych przypadkach taka sama,
ale ustawienie pola timeZone
powoduje przypisanie do wydarzenia strefy czasowej, tak jak
po ustawieniu strefy czasowej wydarzenia za pomocą Kalendarza.
Interfejs:
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.