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 są użytkownicy lub co robią, w tym czy są w czasie skupienia, poza biurem lub pracują w określonej lokalizacji.

W Kalendarzu Google użytkownicy mogą tworzyć wydarzenia związane z czasem skupienia, nieobecnością w biurze i miejscem 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 wydarzeń dotyczących stanu Kalendarza

Możesz odczytywać i wyświetlać wydarzenia dotyczące 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 ma żądaną wartość, i zapoznaj się z odpowiednim polem, aby uzyskać szczegółowe informacje o stanie utworzonym przez użytkownika w Kalendarzu Google:

Subskrybowanie zmian w zdarzeniach stanu

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

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

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

Tworzenie i aktualizowanie wydarzeń stanu kalendarza

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

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

Tworzenie czasu skupienia

Aby utworzyć wydarzenie typu czas skupienia:

  • Ustaw eventType na 'focusTime'.
  • Uwzględnij pole focusTimeProperties.
  • W polu transparency ustaw wartość 'opaque'.
  • Ustaw pola start i end wydarzenia tak, aby było ono wydarzeniem czasowym (z określonymi godzinami rozpoczęcia i zakończenia).
    Czas skupienia nie może być wydarzeniem całodniowym.

Szczegółowe informacje o tej funkcji znajdziesz w artykule Używanie czasu skupienia w Kalendarzu Google.

Tworzenie informacji o nieobecności w biurze

Aby utworzyć wydarzenie dotyczące nieobecności w biurze:

  • Ustaw eventType na 'outOfOffice'.
  • Uwzględnij pole outOfOfficeProperties.
  • W polu transparency ustaw wartość 'opaque'.
  • Ustaw pola start i end wydarzenia tak, aby było ono wydarzeniem czasowym (z określonymi godzinami rozpoczęcia i zakończenia).
    Wydarzenia poza biurem nie mogą być wydarzeniami całodniowymi.

Szczegółowe informacje o tej funkcji znajdziesz w artykule Informowanie o nieobecności w biurze.

Tworzenie lokalizacji miejsca pracy

Aby utworzyć zdarzenie dotyczące lokalizacji miejsca pracy:

  • Ustaw eventType na 'workingLocation'.
  • Uwzględnij pole workingLocationProperties.
  • W polu visibility ustaw wartość 'public'.
  • W polu transparency ustaw wartość 'transparent'.

  • Ustaw pola start i end zdarzenia na jedną z tych wartości:

    • wydarzenie z określonym czasem rozpoczęcia i zakończenia;
    • Wydarzenie całodniowe (z określoną datą rozpoczęcia i zakończenia), które trwa dokładnie jeden dzień.

    Wydarzenia związane z lokalizacją miejsca pracy, które trwają cały dzień, nie mogą obejmować kilku dni, ale wydarzenia z określonym czasem trwania mogą.

Te pola są opcjonalne, ale zalecane, aby zapewnić użytkownikom jak największą wygodę podczas wstawiania elementu officeLocation:

Tworzenie i aktualizowanie zdarzeń związanych z miejscem pracy za pomocą punktów końcowych wsadowych 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 miejscem pracy, które nakładają się na siebie, co oznacza, że w danym momencie może być ustawionych kilka miejsc pracy. W sytuacjach, gdy użytkownikowi można wyświetlić tylko jedną lokalizację, powinna być ona wyświetlana spójnie w różnych aplikacjach. Podczas tego procesu kieruj się tymi wskazówkami, aby wybrać wydarzenie do wyświetlenia:

  • Wydarzenia z określonym czasem mają pierwszeństwo przed wydarzeniami całodniowymi.
  • Wydarzenia pojedyncze mają pierwszeństwo przed wydarzeniami cyklicznymi i ich wyjątkami.
  • Wydarzenia, które zaczynają się później, mają wyższy priorytet niż te, które zaczynają się wcześniej.
  • Wydarzenia o krótszym czasie trwania mają pierwszeństwo przed wydarzeniami o dłuższym czasie trwania.
  • Zdarzenia utworzone niedawno mają pierwszeństwo przed zdarzeniami utworzonymi wcześniej.
  • Częściowo pokrywające się wydarzenia powinny być wyświetlane jako 2 różne wydarzenia, z których każde ma własną lokalizację pracy.

Tworzenie zdarzeń stanu 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 pokazują, 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. 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, 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 objęty programem Developer Preview, 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ć listę zdarzeń stanu w głównym kalendarzu.

  1. Wklej w edytorze kodu ten tekst:

    /** 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/workspace/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/workspace/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/workspace/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/workspace/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ę, 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.