Zarządzanie wydarzeniami związanymi z czasem skupienia, nieobecnością w biurze i lokalizacją miejsca pracy

Na tej stronie dowiesz się, jak używać interfejsu Google Calendar API do tworzenia wydarzeń, które pokazują stan użytkowników Kalendarza Google. Zdarzenia stanu opisują, gdzie znajdują się użytkownicy lub co robią, m.in. czy są w czasie pracy, nieobecni w pracy czy pracują z określonej lokalizacji.

W Kalendarzu Google użytkownicy mogą tworzyć wydarzenia dotyczące czasu skupienia, nieobecności w pracy i miejsca pracy, aby wskazać swój niestandardowy stan i lokalizację. Te funkcje są dostępne tylko w kalendarzach głównych i dla niektórych użytkowników Kalendarza Google.

Więcej informacji znajdziesz w artykułach Korzystanie z czasu na skupienie w Kalendarzu Google i Włączanie i wyłączanie lokalizacji miejsca pracy dla użytkowników.

Odczytywanie i wyświetlanie zdarzeń stanu Kalendarza

Możesz odczytywać i wyświetlać listę zdarzeń stanu Kalendarza w zasobie Events interfejsu Calendar API.

Aby odczytać zdarzenie stanu, użyj metody events.get, podając eventId zdarzenia.

Aby wyświetlić listę zdarzeń stanu, użyj metody events.list, podając w polu eventTypes co najmniej jedną z tych wartości:

  • 'focusTime'
  • 'outOfOffice'
  • 'workingLocation'

Następnie w zwróconych obiektach Event sprawdź, czy pole eventType zawiera żądaną wartość. Aby uzyskać szczegółowe informacje o stanie utworzonym przez użytkownika w Kalendarzu Google, odszukaj odpowiednie pole:

Subskrybowanie zmian w zdarzeniach stanu

Możesz subskrybować zmiany zdarzeń stanu w zasobie Events interfejsu Calendar API.

Użyj metody events.watch, podając calendarId Kalendarza, do którego chcesz się zasubskrybować, oraz co najmniej jedną z tych wartości w polu eventTypes:

  • 'focusTime'
  • 'outOfOffice'
  • 'workingLocation'

Tworzenie i aktualizowanie zdarzeń stanu w kalendarzu

Aby utworzyć zdarzenie stanu, utwórz instancję zasobu Events za pomocą metody events.insert, ustawiając wymagane pola dla danego typu zdarzenia.

Jeśli zaktualizujesz zdarzenie stanu za pomocą metody events.update, zdarzenie musi zawierać wymagane pola.

Tworzenie czasu skupienia

Aby utworzyć wydarzenie typu czas skupienia:

  • Ustaw eventType na 'focusTime'.
  • Dołącz pole focusTimeProperties.
  • W polu transparency ustaw wartość 'opaque'.
  • Ustaw pola start i end jako zdarzenie czasowe (z określonymi godzinami rozpoczęcia i zakończenia).
    Czas skupienia nie może być wydarzeniem całodniowym.

Więcej informacji o tej funkcji znajdziesz w artykule Używanie czasu skupienia w Kalendarzu Google.

Tworzenie informacji o nieobecności

Aby utworzyć zdarzenie nieobecności w biurze:

  • Ustaw eventType na 'outOfOffice'.
  • Dołącz pole outOfOfficeProperties.
  • W polu transparency ustaw wartość 'opaque'.
  • Ustaw pola start i end jako zdarzenie czasowe (z określonymi godzinami rozpoczęcia i zakończenia).
    Wydarzenia poza biurem nie mogą być całodniowymi wydarzeniami.

Więcej informacji o tej funkcji znajdziesz w artykule Informowanie o nieobecności w biurze.

Tworzenie miejsca pracy

Aby utworzyć zdarzenie dotyczące miejsca pracy:

  • Ustaw eventType na 'workingLocation'.
  • Dołącz pole workingLocationProperties.
  • W polu visibility ustaw wartość 'public'.
  • W polu transparency ustaw wartość 'transparent'.

  • W polu start i end zdarzenia ustaw:

    • wydarzenie o określonym czasie trwania (z określonymi godzinami rozpoczęcia i zakończenia);
    • Wydarzenie całodniowe (z określonymi datami rozpoczęcia i zakończenia), które trwa dokładnie jeden dzień.

    Wydarzenia całodniowe związane z lokalizacją miejsca pracy nie mogą obejmować kilku dni, ale wydarzenia czasowe mogą.

Te pola są opcjonalne, ale zalecamy ich używanie, aby zapewnić użytkownikom jak najlepsze wrażenia podczas wstawiania officeLocation:

Tworzenie i aktualizowanie zdarzeń dotyczących miejsca pracy za pomocą punktów końcowych zbiorczego nie jest obsługiwane.

Szczegółowe informacje o tej funkcji znajdziesz w artykułach Ustawianie godzin pracy i lokalizacji oraz Włączanie i wyłączanie lokalizacji miejsca pracy dla użytkowników.

Jak wyświetlać nakładające się zdarzenia dotyczące lokalizacji miejsca pracy

Użytkownik może mieć w kalendarzu kilka wydarzeń związanych z lokalizacją miejsca pracy, które nakładają się na siebie, co oznacza, że w danym momencie może być ustawionych kilka lokalizacji miejsca pracy. W sytuacji, gdy użytkownikowi można wyświetlić tylko jedną lokalizację, należy ją wyświetlać w sposób spójny w różnych aplikacjach. Aby wybrać wydarzenie do wyświetlenia, kieruj się tymi wskazówkami:

  • Zdarzenia z zaplanowanym czasem mają pierwszeństwo przed wydarzeniami całodniowymi.
  • Pojedyncze zdarzenia mają pierwszeństwo przed zdarzeniami cyklicznymi i ich wyjątkami.
  • Wydarzenia, które zaczynają się później, mają pierwszeństwo przed tymi, które zaczynają się wcześniej.
  • Wydarzenia o krótszym czasie trwania mają pierwszeństwo przed tymi o dłuższym czasie trwania.
  • Zdarzenia utworzone później mają pierwszeństwo przed zdarzeniami utworzonymi wcześniej.
  • Częściowo nakładające się wydarzenia powinny być wyświetlane jako 2 różne wydarzenia z osobną lokalizacją.

Tworzenie zdarzeń stanu 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.

Z tych instrukcji dowiesz się, jak zarządzać zdarzeniami stanu 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 lewym panelu. 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, wykonaj te czynności, aby zaktualizować projekt powiązany ze skryptem.

  1. Po lewej stronie edytora kliknij Ustawienia projektu.
  2. W sekcji Projekt Google Cloud Platform (GCP) kliknij Zmień projekt.
  3. Wpisz numer projektu Google Cloud, który jest w ramach programu podglądu dla deweloperów, i kliknij Ustaw projekt.
  4. Po lewej stronie wybierz Edytor , aby wrócić do edytora kodu.

Dodawanie kodu do skryptu

Poniższy przykładowy kod pokazuje, jak tworzyć, odczytywać i wyświetlać zdarzenia stanu w głównym kalendarzu.

  1. Wklej ten kod do edytora kodu.

    /** Creates a focus time event. */
function createFocusTime() {
  const event = {
    start: { dateTime: '2023-11-14T10:00:00+01:00' },
    end: { dateTime: '2023-11-14T12:00:00+01:00' },
    eventType: 'focusTime',
    focusTimeProperties: {
      chatStatus: 'doNotDisturb',
      autoDeclineMode: 'declineOnlyNewConflictingInvitations',
      declineMessage: 'Declined because I am in focus time.',
    }
  }
  createEvent(event);
}

/** Creates an out of office event. */
function createOutOfOffice() {
  const event = {
    start: { dateTime: '2023-11-15T10:00:00+01:00' },
    end: { dateTime: '2023-11-15T18:00:00+01:00' },
    eventType: 'outOfOffice',
    outOfOfficeProperties: {
      autoDeclineMode: 'declineOnlyNewConflictingInvitations',
      declineMessage: 'Declined because I am on vacation.',
    }
  }
  createEvent(event);
}

/** Creates a working location event. */
function createWorkingLocation() {
  const event = {
    start: { date: "2023-06-01" },
    end: { date: "2023-06-02" },
    eventType: "workingLocation",
    visibility: "public",
    transparency: "transparent",
    workingLocationProperties: {
      type: 'customLocation',
      customLocation: { label: "a custom location" },
    }
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {
  const calendarId = 'primary';

  try {
    var response = Calendar.Events.insert(event, calendarId);
    var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
    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() {
  const calendarId = 'primary';

  // Replace with a valid eventId.
  const eventId = "sample-event-id";

  try {
    var response = Calendar.Events.get(calendarId, eventId);
    var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
    console.log(event);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Lists focus time events. */
function listFocusTimes() {
  listEvents('focusTime');
}

/** Lists out of office events. */
function listOutOfOffices() {
  listEvents('outOfOffice');
}

/** Lists working location events. */
function listWorkingLocations() {
  listEvents('workingLocation');
}

/**
  * Lists events with the given event type.
  * See https://developers.google.com/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = 'default') {
  const calendarId = 'primary'

  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: [eventType],
    showDeleted: false,
    singleEvents: true,
    timeMax: '2023-04-01T00:00:00+01:00',
    timeMin: '2023-03-27T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(calendarId, optionalArgs);
    response.items.forEach(event =>
      console.log(eventType === 'workingLocation' ? parseWorkingLocation(event) : event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Parses working location properties of an event into a string.
  * See https://developers.google.com/calendar/api/v3/reference/events#resource
  */
function parseWorkingLocation(event) {
  if (event.eventType != "workingLocation") {
    throw new Error("'" + event.summary + "' is not a working location event.");
  }

  var location = 'No Location';
  const workingLocation = event.workingLocationProperties;
  if (workingLocation) {
    if (workingLocation.type === 'homeOffice') {
      location = 'Home';
    }
    if (workingLocation.type === 'officeLocation') {
      location = workingLocation.officeLocation.label;
    }
    if (workingLocation.type === 'customLocation') {
      location = workingLocation.customLocation.label;
    }
  }
  return `${event.start.date}: ${location}`;
}

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.