Typy zdarzeń

Na tej stronie znajdziesz opis właściwości eventType oraz specyfikacje typów wydarzeń dostępnych w interfejsie Google Calendar API.

Kalendarz Google umożliwia tworzenie ogólnych wydarzeń, a także wydarzeń przeznaczonych do konkretnych zastosowań i z właściwościami niestandardowymi.

Typ zdarzenia można znaleźć w tych miejscach w interfejsie API:

  • Wszystkie zdarzenia są zwracane z wartością eventType.
  • eventType musi być ustawiony podczas tworzenia lub aktualizowania zasobu wydarzenia. Jeśli zasada jest nieskonfigurowana, używany jest typ 'default'.
  • eventTypes można określić w wywołaniu Events:list w celu wyświetlenia listy zdarzeń określonych typów. Jeśli nie określisz typu, zwracane będą wszystkie typy zdarzeń.
  • eventTypes można określić w wywołaniu Events:watch w celu subskrybowania aktualizacji dotyczących zdarzeń określonych typów. Jeśli nie określisz typu, w wyniku żądania nastąpi subskrypcja wszystkich typów zdarzeń.

Wydarzenie domyślne

Wydarzenia typu default są tworzone i używane jako jeden z głównych zasobów interfejsu Google Calendar API. Obsługują one szeroki zakres właściwości, które można wykorzystać do dalszego dostosowywania zdarzenia.

Aby zacząć korzystać z wydarzeń w Kalendarzu Google, zapoznaj się z artykułem Tworzenie wydarzeń.

Urodziny

Urodziny to specjalne wydarzenia całodniowe, które powtarzają się co roku.

Użytkownicy mogą ręcznie tworzyć wydarzenia urodzinowe w Kalendarzu Google. Informacje o urodzinach są synchronizowane z Kalendarzem Google, gdy użytkownicy dodają osobę wraz z datą jej urodzin i innymi ważnymi datami do Kontaktów Google. Urodziny użytkowników są też synchronizowane z Kalendarzem Google z profilu na koncie Google.

Interfejs Google Calendar API obsługuje metody get, instances i list do odczytywania zdarzeń związanych z urodzinami. eventTypes można ustawić na 'birthday', aby wyświetlać tylko wydarzenia związane z urodzinami. Jeśli nie określisz typu, urodziny będą wyświetlane razem z innymi typami wydarzeń.

W zwróconych obiektach Event sprawdź pole birthdayProperties, aby uzyskać więcej informacji o tym specjalnym wydarzeniu. birthdayProperties ma te pola:

  • type: rodzaj tego specjalnego wydarzenia, np. urodziny, rocznica lub inna ważna data.
  • customTypeName: etykieta określona przez użytkownika dla tego wydarzenia specjalnego. To pole jest wypełniane, jeśli element type ma wartość 'custom'.
  • contact: Nazwa zasobu kontaktu, z którym powiązane jest to wydarzenie specjalne (jeśli występuje). Ma on format 'people/c12345' i może służyć do pobierania danych kontaktowych z interfejsu People API.

Interfejs API umożliwia tworzenie wydarzeń związanych z urodzinami za pomocą metody insert o tych specyfikacjach:

  • eventType ma wartość 'birthday'.
  • Pola start i end muszą określać wydarzenie całodniowe, które trwa dokładnie 1 dzień.
  • Wartość pola visibility musi być 'private'.
  • Wartość pola transparency musi być 'transparent'.
  • Musi mieć roczne powtarzanie, co oznacza, że pole recurrence musi mieć wartość 'RRULE:FREQ=YEARLY'. Wydarzenia związane z urodzinami przypadającymi 29 lutego muszą mieć następującą regułę powtarzania:'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'.
  • Może mieć colorId, summary i reminders.
  • Może zawierać birthdayProperties. Jeśli wartość została określona, type musi mieć wartość 'birthday', a wartości customTypeName i contact muszą być puste.
  • Nie może zawierać żadnych innych właściwości zdarzenia.

Interfejs API umożliwia aktualizowanie colorId, summary i reminders wydarzeń związanych z urodzinami za pomocą metod update i patch. Pola start i end można też zaktualizować, aby zmienić datę wydarzenia. W takim przypadku nowe wartości muszą określać wydarzenie całodniowe, które trwa dokładnie 1 dzień. Szczegółów dotyczących czasu wydarzenia urodzinowego nie można zaktualizować, jeśli jest ono połączone z contact lub jego type to 'self'.

Interfejs Google Calendar API nie zezwala na tworzenie wydarzeń związanych z urodzinami z niestandardowymibirthdayProperties ani na aktualizowanie tych właściwości. Ważne daty można edytować za pomocą interfejsu People API, a zmiany są synchronizowane z Kalendarzem Google. Podobnie użytkownicy mogą edytować datę urodzenia na profilu konta Google, a zmiany są synchronizowane z Kalendarzem Google.

Żądania, które próbują utworzyć lub zaktualizować datę urodzenia w nieobsługiwany sposób, zakończą się niepowodzeniem. W takim przypadku sprawdź komunikat o błędzie, aby zidentyfikować problem.

Interfejs API obsługuje operację import w przypadku wydarzeń urodzinowych, ale wydarzenie zostanie zaimportowane jako domyślne. Inaczej mówiąc, eventType będzie 'default'.

Interfejs API obsługuje metodę watch, która umożliwia subskrybowanie zmian w wydarzeniach związanych z urodzinami w Kalendarzu Google. eventTypes można ustawić na 'birthday', aby subskrybować aktualizacje wydarzeń związanych z urodzinami. Jeśli nie określisz typu, subskrybowane będą wszystkie typy zdarzeń, w tym urodziny.

Wydarzenia związane z urodzinami można usuwać za pomocą metody delete interfejsu Google Calendar API. Usunięcie wydarzenia urodzinowego z Kalendarza Google nie ma wpływu na dane w Kontaktach Google ani w profilu konta Google.

Zmiana organizatora wydarzenia urodzinowego za pomocą metod move lub update nie jest obsługiwana.

Wydarzenia z Gmaila

Wydarzenia generowane automatycznie z Gmaila mają typ 'fromGmail'.

Interfejs Google Calendar API nie umożliwia tworzenia tego typu wydarzeń za pomocą metody insert.

Interfejs API umożliwia aktualizowanie właściwości rozszerzonych colorId, reminders, visibility, transparency, status, attendees, private i shared za pomocą metod update i patch.

Interfejs API obsługuje metody get i list do odczytywania zdarzeń z Gmaila. eventTypes może mieć wartość 'fromGmail', aby wyświetlać tylko wydarzenia wygenerowane w Gmailu. Jeśli nie określisz typu, wydarzenia z Gmaila będą wyświetlane razem z innymi typami wydarzeń.

Interfejs API obsługuje metodę watch, która umożliwia subskrybowanie zmian w wydarzeniach z Gmaila w Kalendarzu Google. Jeśli nie określisz typu, subskrybowane będą wszystkie typy zdarzeń, w tym 'fromGmail'.

Wydarzenia z Gmaila można usuwać za pomocą metody delete interfejsu Google Calendar API.

Zmiana organizatora wydarzenia z Gmaila za pomocą metod move lub update nie jest obsługiwana.

Czas skupienia, status „poza biurem” i lokalizacja miejsca pracy

Interfejs Google Calendar API może służyć do tworzenia wydarzeń i zarządzania nimi, które pokazują stan użytkowników Kalendarza Google.

Te funkcje są dostępne tylko w kalendarzach głównych i dla niektórych użytkowników Kalendarza Google. Więcej informacji znajdziesz w artykule Zarządzanie czasem na skupienie, wydarzeniami „poza biurem” i wydarzeniami związanymi z miejscem pracy.

Poznaj typy zdarzeń w Google Apps Script

Google Apps Script to oparty na JavaScript internetowy język skryptów, który umożliwia tworzenie aplikacji biznesowych zintegrowanych z Google Workspace. Skrypty są tworzone w edytorze kodu w przeglądarce, a następnie przechowywane i uruchamiane na serwerach Google. Aby zacząć korzystać z Apps Script do wysyłania żądań do interfejsu Google Calendar API, zapoznaj się też z szybkim wprowadzeniem do Google Apps Script.

Poniższe instrukcje opisują, jak odczytywać wydarzenia i nimi zarządzać za pomocą interfejsu Google Calendar API jako zaawansowanej usługi w Google Apps Script. Pełną listę zasobów i metod interfejsu Google Calendar API znajdziesz w dokumentacji.

Tworzenie i konfigurowanie skryptu

  1. Utwórz skrypt, wchodząc na script.google.com/create.
  2. W panelu po lewej stronie obok pozycji Usługi kliknij Dodaj usługę .
  3. Wybierz Google Calendar API i kliknij Dodaj.
  4. Po włączeniu interfejs API pojawi się w panelu po lewej stronie. Dostępne metody i klasy w interfejsie API można wyświetlić za pomocą słowa kluczowego Calendar w edytorze.

(Opcjonalnie) Aktualizowanie projektu Google Cloud

Każdy projekt Google Apps Script jest powiązany z projektem Google Cloud. Skrypt może korzystać z domyślnego projektu, który Google Apps Script tworzy automatycznie. Jeśli chcesz użyć niestandardowego projektu Google Cloud, zapoznaj się z artykułem Przełączanie na inny standardowy projekt w Cloud. Po skonfigurowaniu projektu Google Cloud wybierz po lewej stronie Edytujący , aby wrócić do edytora kodu.

Dodawanie kodu do skryptu

Poniższy przykładowy kod pokazuje, jak wyświetlać, odczytywać i tworzyć zdarzenia z różnymi wartościami eventType.

  1. Wklej w edytorze kodu ten tekst:

    const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => console.log(event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
  */
function readEvent() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

    Zastąp następujące elementy:

    • CALENDAR_ID: adres e-mail kalendarza, z którego mają być pobierane wydarzenia i w którym mają być tworzone. Ta stała jest początkowo ustawiona na wartość 'primary', która jest słowem kluczowym umożliwiającym dostęp do kalendarza głównego zalogowanego użytkownika. Zmiana tej wartości umożliwia odczytywanie wydarzeń w kalendarzach innych użytkowników, do których masz dostęp.
    • EVENT_ID: identyfikator zdarzenia. Aby pobrać identyfikatory wydarzeń, możesz wywołać metodę Events:list.

Uruchamianie przykładowego kodu

  1. Nad edytorem kodu wybierz funkcję, którą chcesz uruchomić, z menu, a następnie kliknij Uruchom.
  2. Przy pierwszym wykonaniu pojawi się prośba o autoryzację dostępu. Sprawdź i zezwalaj na dostęp Apps Script do kalendarza.
  3. Wyniki wykonania skryptu możesz sprawdzić w dzienniku wykonania, który pojawi się u dołu okna.