Ta strona została przetłumaczona przez Cloud Translation API.

Kalendarze i wydarzenia

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 i end.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 i end.date określają, kiedy się one pojawiają. Pamiętaj, że pole strefy czasowej nie ma znaczenia w przypadku wydarzeń całodniowych.

Rozpoczęcie i zakończenie wydarzenia musi być zaplanowane na cały dzień lub oba dni. Na przykład nie ma znaczenia, aby określić start.date i end.dateTime.

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 lub WEEKLY).
INTERVAL – współpracuje 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,

Aby określić koniec powtarzania wydarzenia, użyj COUNT lub UNTIL. Nie używaj obu w tej samej regule.
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 to BYMONTH, BYYEARDAY i BYHOUR.

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() i instances() są zwracane w strefie czasowej określonej w parametrze timeZone. 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() i instances() 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ład 2017-01-25T09:00:00-0500.
Określ godzinę bez przesunięcia, na przykład 2017-01-25T09:00:00, pozostawiając pole timeZone 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 polu timeZone 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ęcia 2017-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.