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

Na tej stronie dowiesz się, jak za pomocą interfejsu Google Calendar API tworzyć wydarzenia, które pokazują status użytkowników Kalendarza Google. Wydarzenia dotyczące statusu informują o tym, gdzie są użytkownicy lub co robią, w tym czy są w trybie skupienia, poza biurem czy pracują z określonej lokalizacji.

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

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

Odczytywanie i wyświetlanie listy wydarzeń dotyczących statusu w kalendarzu

Wydarzenia dotyczące statusu w kalendarzu możesz odczytywać i wyświetlać w zasobie Events interfejsu Calendar API.

Aby odczytać wydarzenie dotyczące statusu, użyj metody events.get, podając eventId wydarzenia.

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

  • '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 statusie utworzonym przez użytkownika w Kalendarzu:

Subskrybowanie zmian w wydarzeniach dotyczących statusu

Możesz subskrybować zmiany w wydarzeniach dotyczących statusu w zasobie Events interfejsu Calendar API.

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

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

Tworzenie i aktualizowanie wydarzeń dotyczących statusu w kalendarzu

Aby utworzyć wydarzenie dotyczące statusu, utwórz instancję zasobu Events za pomocą metody events.insert, ustawiając wymagane pola dla typu wydarzenia.

Jeśli zaktualizujesz wydarzenie dotyczące statusu za pomocą metody events.update, wydarzenie musi zachować wymagane pola.

Tworzenie czasu skupienia

Aby utworzyć wydarzenie typu czas skupienia:

  • Ustaw eventType na 'focusTime'.
  • Dodaj pole focusTimeProperties.
  • Ustaw transparency pole na 'opaque'.
  • Ustaw pola start i end wydarzenia tak, aby było to wydarzenie z określonym czasem (z podanymi godzinami rozpoczęcia i zakończenia). Wydarzenia typu czas skupienia nie mogą być wydarzeniami całodniowymi.

Szczegółowe informacje o tej funkcji znajdziesz w artykule Korzystanie z czasu skupienia w Google Kalendarz.

Tworzenie wydarzenia „poza biurem”

Aby utworzyć wydarzenie „poza biurem”:

  • Ustaw eventType na 'outOfOffice'.
  • Dodaj pole outOfOfficeProperties.
  • Ustaw transparency pole na 'opaque'.
  • Ustaw pola start i end wydarzenia tak, aby było to wydarzenie z określonym czasem (z podanymi godzinami rozpoczęcia i zakończenia). Wydarzenia „poza biurem” nie mogą być wydarzeniami całodniowymi.

Szczegółowe informacje o tej funkcji znajdziesz w artykule Pokazywanie, kiedy jesteś poza biurem.

Tworzenie lokalizacji miejsca pracy

Aby utworzyć wydarzenie dotyczące lokalizacji miejsca pracy:

  • Ustaw eventType na 'workingLocation'.
  • Dodaj pole workingLocationProperties.
  • Ustaw pole visibility na 'public'.
  • Ustaw transparency pole na 'transparent'.

  • Ustaw pola start i end wydarzenia tak, aby było to:

    • wydarzenie z określonym czasem (z podanymi godzinami rozpoczęcia i zakończenia);
    • wydarzenie całodniowe (z podanymi datami rozpoczęcia i zakończenia), które trwa dokładnie 1 dzień.

    Całodniowe wydarzenia dotyczące lokalizacji miejsca pracy nie mogą trwać dłużej niż 1 dzień, ale wydarzenia z określonym czasem mogą.

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

Punkty końcowe zbiorcze nie obsługują tworzenia i aktualizowania wydarzeń dotyczących lokalizacji miejsca pracy.

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.

Wyświetlanie nakładających się wydarzeń dotyczących lokalizacji miejsca pracy

Użytkownik może mieć w kalendarzu kilka nakładających się wydarzeń dotyczących lokalizacji miejsca pracy, co oznacza, że w danym momencie może być ustawionych kilka lokalizacji miejsca pracy. W sytuacjach, gdy użytkownikowi można wyświetlić tylko jedną lokalizację, wyświetlaj ją konsekwentnie w różnych aplikacjach. W takim przypadku wybierz wydarzenie, które ma być wyświetlane, zgodnie z tymi wytycznymi:

  • 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ą pierwszeństwo przed wydarzeniami, które zaczynają się wcześniej.
  • Wydarzenia o krótszym czasie trwania mają pierwszeństwo przed wydarzeniami o dłuższym czasie trwania.
  • Wydarzenia utworzone niedawno mają pierwszeństwo przed wydarzeniami utworzonymi wcześniej.
  • Wydarzenia częściowo nakładające się wyświetlaj jako 2 różne wydarzenia, z których każde ma własną lokalizację miejsca pracy.

Tworzenie wydarzeń dotyczących statusu w Google Apps Script

Apps Script to język skryptów w chmurze oparty na JavaScript, 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 Calendar API, zapoznaj się z przewodnikiem Apps Script Szybki start.

Z tych instrukcji dowiesz się, jak zarządzać wydarzeniami dotyczącymi statusu za pomocą interfejsu Calendar API jako usługi zaawansowanej w Apps Script. Pełną listę zasobów i metod interfejsu Calendar API znajdziesz w dokumentacji.

Tworzenie i konfigurowanie skryptu

  1. Utwórz skrypt, otwierając stronę script.google.com/create.
  2. W panelu po lewej stronie obok Usługi kliknij Dodaj usługę .
  3. Wybierz Calendar API i kliknij Dodaj.
  4. Po włączeniu interfejsu API pojawi się on w panelu po lewej stronie. Aby wyświetlić listę dostępnych metod i klas w interfejsie API, wpisz Calendar w edytorze.

(Opcjonalnie) Aktualizowanie projektu w chmurze

Każdy projekt Apps Script jest powiązany z projektem w chmurze. Skrypt może korzystać z projektu domyślnego, który Apps Script tworzy automatycznie. Jeśli chcesz używać niestandardowego projektu w chmurze, 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 kliknij Edytor aby wrócić do edytora kodu.

Dodawanie kodu do skryptu

Z tego przykładowego kodu dowiesz się, jak tworzyć, odczytywać i wyświetlać listę wydarzeń dotyczących statusu w kalendarzu głównym.

  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/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 uruchomieniu skryptu 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 Dzienniku wykonania , który pojawi się u dołu okna.