Typy zdarzeń

Na tej stronie znajdziesz informacje o właściwości eventType oraz specyfikacje typów zdarzeń dostępnych w interfejsie API Kalendarza Google.

Kalendarz Google umożliwia użytkownikom 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 parametrem eventType.
  • eventTypetrzeba ustawić podczas tworzenia lub aktualizowania zasobu wydarzenia. Jeśli to ustawienie nie jest skonfigurowane, używany jest typ 'default'.
  • eventTypes może być określony w wywołaniu Events:list w celu wyświetlenia zdarzeń określonych typów. Jeśli nie podasz typu, zwrócone zostaną wszystkie typy zdarzeń.
  • eventTypesmoże być określony w wywołaniu Events:watch, aby subskrybować aktualizacje dotyczące zdarzeń określonych typów. Jeśli nie określisz typu, żądanie spowoduje subskrypcję wszystkich typów zdarzeń.

Domyślne zdarzenie

Zdarzenia o typie 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, przeczytaj artykuł 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. Dodatkowo 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. Data urodzenia użytkownika jest też synchronizowana z Kalendarzem Google z profilu na koncie Google.

Interfejs Google Calendar API obsługuje metody get, instances i list do odczytywania zdarzeń urodzinowych. Aby wyświetlić tylko urodziny, ustaw wartość eventTypes na 'birthday'. 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 szczególnym zdarzeniu. birthdayProperties zawiera te pola:

  • type: typ wydarzenia specjalnego, np. urodziny, rocznica lub inna ważna data.
  • customTypeName: etykieta określona przez użytkownika dla tego specjalnego wydarzenia. Jest wypełnione, jeśli ustawienie type to 'custom'.
  • contact: nazwa zasobu kontaktu, z którym jest powiązane to specjalne wydarzenie (jeśli istnieje). Ma on format 'people/c12345' i może służyć do pobierania danych kontaktowych z interfejsu People API.

Interfejs API umożliwia tworzenie zdarzeń urodzinowych za pomocą metody insert o tych specyfikacjach:

  • eventType ma wartość 'birthday'.
  • Pola start i end muszą definiować całodniowe zdarzenie, które trwa dokładnie 1 dzień.
  • Wartość pola visibility musi wynosić 'private'.
  • Wartość pola transparency musi wynosić 'transparent'.
  • Musisz mieć coroczną powtarzalność, co oznacza, że pole recurrence musi mieć wartość 'RRULE:FREQ=YEARLY'. Wydarzenia urodzinowe przypadające 29 lutego muszą mieć tę regułę powtarzania: 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'.
  • Może zawierać colorId, summary i reminders.
  • Może zawieraćbirthdayProperties. Jeśli wartość została określona, parametr type musi mieć wartość 'birthday', a parametry customTypeName i contact muszą być puste.
  • Nie może mieć żadnych innych właściwości zdarzenia.

Interfejs API umożliwia aktualizowanie pól colorId, summary i reminders zdarzeń urodzinowych za pomocą metod update i patch. Aby zmienić datę wydarzenia, możesz też zaktualizować pola start i end. W takim przypadku nowe wartości muszą definiować całodniowe zdarzenie, które trwa dokładnie 1 dzień. Szczegółów daty wydarzenia urodzinowego nie można zmienić, jeśli jest ono powiązane z contact lub jeśli jego type to 'self'.

Interfejs Google Calendar API nie pozwala na tworzenie wydarzeń urodzinowych za pomocą niestandardowych birthdayProperties 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ć swoją datę urodzenia w profilu konta Google, a ta data jest synchronizowana z Kalendarzem Google.

Żądania o utworzenie lub zaktualizowanie urodzin w nieobsługiwany sposób nie będą realizowane. W takim przypadku sprawdź komunikat o błędzie, aby zidentyfikować problem.

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

Interfejs API obsługuje metodę watch, która umożliwia subskrybowanie zmian w wydarzeniach urodzinowych w Kalendarzu Google. Aby subskrybować powiadomienia o urodzinach, możesz ustawić wartość eventTypes na 'birthday'. Jeśli nie wybierzesz żadnego typu, subskrypcja obejmie wszystkie typy zdarzeń, w tym urodziny.

Wydarzenia urodzinowe można usunąć za pomocą metody delete interfejsu Google Calendar API. Usunięcie wydarzenia urodzinowego z Kalendarza Google nie wpłynie na dane w Kontaktach Google ani na profil 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 zdarzenia 'fromGmail'.

Interfejs Google Calendar API nie pozwala na tworzenie tego typu wydarzenia za pomocą metody insert.

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

Interfejs API obsługuje metody get i list do odczytywania zdarzeń z Gmaila. Wartość eventTypes możesz ustawić na 'fromGmail', aby wyświetlić tylko zdarzenia wygenerowane przez Gmaila. Jeśli nie określisz typu, zdarzenia z Gmaila będą wyświetlane razem z innymi typami zdarzeń.

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

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

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

Czas na skupienie, status „poza biurem” i lokalizacja miejsca pracy

Interfejsu Google Calendar API można używać 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, statusem „poza biurem” i zdarzeniami dotyczącymi miejsca pracy.

Poznawanie typów zdarzeń w Google Apps Script

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

W tych instrukcjach dowiesz się, jak odczytywać zdarzenia 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. Aby utworzyć skrypt, otwórz stronę 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ć, używając w edytorze słowa kluczowego Calendar.

(Opcjonalnie) Zmień projekt Google Cloud

Każdy projekt Google Apps Script ma powiązany projekt Google Cloud. Twój skrypt może korzystać z projektu domyślnego utworzonego automatycznie przez Google Apps Script. Jeśli chcesz użyć niestandardowego projektu Google Cloud, zapoznaj się z artykułem Przełączanie się na inny standardowy projekt Cloud. Po skonfigurowaniu projektu Google Cloud po lewej stronie wybierz Edytor , aby wrócić do edytora kodu.

Dodawanie kodu do skryptu

Poniższy przykładowy kod pokazuje, jak wyświetlać, odczytywać i tworzyć zdarzenia o różnych wartościach eventType.

  1. Wklej ten kod do edytora kodu.

    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/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/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/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, w którym mają być pobierane i tworzone wydarzenia. Ta stała jest początkowo ustawiona na'primary', czyli słowo kluczowe, które umożliwia dostęp do głównego kalendarza zalogowanego użytkownika. Zmiana tej wartości umożliwia odczytywanie wydarzeń z kalendarzy innych użytkowników, do których masz dostęp.
    • EVENT_ID: identyfikator zdarzenia. Aby pobrać identyfikatory zdarzeń, możesz wywołać Events:list.

Uruchamianie przykładowego kodu

  1. Nad edytorem kodu wybierz funkcję do uruchomienia z menu i kliknij Uruchom.
  2. Podczas pierwszego uruchomienia pojawi się prośba o autoryzację dostępu. Sprawdź i zezwól Apps Script na dostęp do kalendarza.
  3. Wyniki wykonania skryptu możesz sprawdzić w logu wykonania, który pojawia się u dołu okna.