Ten przewodnik opisuje kalendarze i wydarzenia oraz 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 identyfikowany przez identyfikator, który jest adresem e-mail. Kalendarze mogą mieć wielu właścicieli.
Zdarzenia
Zdarzenie to obiekt powiązany z określonym zakresem dat lub godzin. Zdarzenia są rozpoznawane za pomocą unikalnego identyfikatora. Oprócz daty rozpoczęcia i 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 to unikalne wystąpienie.
- Zdarzenie cykliczne ma wiele wystąpień.
Wydarzenia mogą też mieć format chronologiczny lub cały dzień:
- Zdarzenie czasowe występuje między 2 określonymi punktami w czasie. Zdarzenia czasowe wykorzystują pola
start.dateTime
iend.dateTime
, aby określić, kiedy występują. - Cały dzień obejmuje cały dzień lub serię kolejnych dni. Wydarzenia całodniowe za pomocą pól
start.date
iend.date
określają, kiedy się one pojawiają. Pamiętaj, że pole strefy czasowej nie ma znaczenia w przypadku wydarzeń całodniowych.
Organizatorzy
Wydarzenia mają jedną organizację, czyli kalendarz zawierający główną kopię wydarzenia. Wydarzenia mogą też mieć wielu uczestników. Uczestnik jest zwykle głównym kalendarzem zaproszonego użytkownika.
Ten diagram przedstawia koncepcyjną relację między kalendarzami, wydarzeniami i innymi powiązanymi elementami:
Kalendarze główne i inne kalendarze
Główny kalendarz to specjalny kalendarz powiązany z jednym kontem użytkownika. Ten kalendarz jest tworzony automatycznie dla każdego nowego konta użytkownika, a jego identyfikator zwykle odpowiada głównemu adresowi e-mail użytkownika. Dopóki konto użytkownika istnieje, jego główny kalendarz nigdy nie może zostać usunięty ani usunięty przez użytkownika. Można ją jednak udostępniać innym użytkownikom.
Oprócz kalendarza głównego możesz wyraźnie utworzyć dowolną liczbę innych kalendarzy, które można modyfikować, usuwać i udostępniać wielu użytkownikom.
Kalendarz i lista kalendarzy
Kolekcja Kalendarze reprezentuje wszystkie istniejące kalendarze. Może być używany do tworzenia i usuwania kalendarzy. Możesz też pobierać i ustawiać właściwości globalne 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 kalendarza dodanych przez użytkownika do listy (jest on wyświetlany w lewym panelu interfejsu internetowego). Możesz używać go do dodawania istniejących kalendarzy do listy użytkowników i usuwania ich z niej. Służy on też do pobierania i ustawiania wartości właściwości kalendarza konkretnych użytkowników, takich jak domyślne przypomnienia. Innym przykładem jest kolor pierwszego planu, ponieważ każdy użytkownik może w tym samym kalendarzu ustawić różne kolory.
W tabeli poniżej znajdziesz porównanie operacji w obu 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żytkownika. |
delete |
Usunięcie kalendarza pomocniczego. | Usunięcie kalendarza z listy użytkownika. |
get |
Pobiera metadane kalendarza, np. tytuł, strefę czasową. | Pobiera metadane plus dostosowane do potrzeb użytkownika, takie jak kolory czy przypomnienia dotyczące zastąpień. |
patch /update |
Modyfikuje metadane kalendarza. | Zmienia właściwości kalendarza dla użytkowników. |
Wydarzenia cykliczne
Niektóre wydarzenia mają miejsce wiele razy w regularnych odstępach czasu, np. w przypadku spotkań tygodniowych, urodzin i świąt. Różne zdarzenia często mają jednakowe czasy rozpoczęcia i zakończenia.
Wydarzenia nazywane są cyklicznymi, jeśli powtarzają się zgodnie z określonym harmonogramem. Pojedyncze wydarzenia 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, tak jakby było to samodzielne wydarzenie);
Pole powtarzania (określające sposób powtarzania wydarzenia).
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 stałą regułę powtarzania zdarzenia. Składa się z kilku elementów. Oto niektóre z nich:
FREQ
– częstotliwość, z jaką wydarzenie ma się powtarzać (np.DAILY
lubWEEKLY
).INTERVAL
– współpracuje zFREQ
, aby określić, jak często wydarzenie ma się powtarzać. Na przykładFREQ=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 toBYMONTH
,BYYEARDAY
iBYHOUR
.
Właściwość RDATE
określa dodatkowe daty lub godziny, w których powinny wystąpić zdarzenia. Na przykład: RDATE;VALUE=DATE:19970101,19970120
.
Służy do dodawania kolejnych wystąpień, które nie są objęte RRULE
.
Właściwość EXDATE
jest podobna do RDATE, ale określa daty lub godziny, w których zdarzenie nie powinno się wydarzyć. Oznacza to, że należy je wykluczyć. Musi wskazywać prawidłową instancję wygenerowaną przez regułę powtarzania.
EXDATE
i RDATE
mogą mieć strefę czasową i muszą być datami (a nie godzinami) dla wydarzeń całodniowych.
Każda z właściwości może pojawić się w polu powtarzania wielokrotnie.
Powtarzanie jest zdefiniowane jako połączenie wszystkich reguł RRULE
i RDATE
pomniejszone o wykluczone przez wszystkie reguły EXDATE
.
Oto kilka przykładów wydarzeń cyklicznych:
Wydarzenie, które odbywa się w godzinach 6–7 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" ], …
Całodniowe wydarzenie rozpoczynające się 1 czerwca 2015 r. i powtarzające się co 3 dni w miesiącu, z wyłączeniem 10 czerwca, 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: wystąpień tego typu w różnym czasie. Instancje te działają jako zdarzenia.
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ędnych wydarzeń cyklicznych, są nazywane wyjątkami.
Na przykład wyjątek może mieć inne podsumowanie, inny czas rozpoczęcia lub dodatkowych uczestników zaproszonych tylko do tej instancji. Możesz też całkowicie anulować instancję bez usuwania wydarzenia cyklicznego (informacje o anulowaniu instancji są widoczne w zdarzeniu status
).
Przykłady obsługi wydarzeń cyklicznych i wystąpień za pomocą interfejsu Google Calendar API znajdziesz tutaj.
Strefy czasowe
Strefa czasowa to region, w którym obowiązuje jednolity czas standardowy. W interfejsie Google Calendar API możesz określić strefy czasowe za pomocą identyfikatorów IANA strefy czasowej.
Możesz ustawić strefę czasową zarówno dla kalendarzy, jak i wydarzeń. Skutki zmian są podane w kolejnych sekcjach.
Strefa czasowa kalendarza
Strefa czasowa kalendarza jest też nazywana domyślną strefą czasową ze względu na wpływ na wyniki zapytań. Strefa czasowa kalendarza wpływa na sposób interpretowania i prezentowania wartości czasu za pomocą metod 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 korzystać ze strefy czasowej kalendarza. - Dopasowanie wydarzeń z całego dnia do zapytań z przedziału czasowego
- Metody
list()
iinstances()
pozwalają określić filtry czasu rozpoczęcia i zakończenia, przy czym metoda zwraca instancje, które należą 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 należą one do specyfikacji filtra.
Strefa czasowa wydarzenia
Instancje zdarzeń mają czas rozpoczęcia i zakończenia. 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ład2017-01-25T09:00:00-0500
. - Określ godzinę bez przesunięcia, na przykład
2017-01-25T09:00:00
, pozostawiając poletimeZone
puste (domyślnie jest używana domyślna strefa czasowa). - Określ godzinę bez przesunięcia, na przykład
2017-01-25T09:00:00
, ale w polutimeZone
określ strefę czasową.
Możesz też podać godziny wydarzeń w strefie czasowej UTC:
- Podaj czas UTC:
2017-01-25T14:00:00Z
lub użyj przesunięcia2017-01-25T14:00:00+0000
.
Wewnętrzna reprezentacja godziny wydarzenia jest taka sama w każdej z tych sytuacji, ale ustawienie pola timeZone
powoduje dołączenie strefy czasowej do wydarzenia tak samo jak w przypadku ustawiania strefy czasowej w interfejsie Kalendarza:
Strefa czasowa wydarzenia cyklicznego
W przypadku wydarzeń cyklicznych zawsze musi być określona jedna strefa czasowa. Jest to konieczne do zwiększenia liczby powtórzeń wydarzenia.