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

Na tej stronie opisujemy, jak za pomocą interfejsu Google Calendar API tworzyć wydarzenia przedstawiające stan użytkowników Kalendarza Google. Zdarzenia związane ze stanem wskazują, gdzie są lub co robią użytkownicy, m.in. czy mają czas skupienia, poza biurem lub pracują w konkretnym miejscu.

W Kalendarzu Google użytkownicy mogą tworzyć wydarzenia typu czas skupienia, poza biurem i lokalizację miejsca pracy, aby określić własny stan i lokalizację. Te funkcje są dostępne tylko w kalendarzach głównych i tylko dla niektórych użytkowników Kalendarza Google.

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 zdarzeń stanu w kalendarzu

Zdarzenia stanu w kalendarzu możesz odczytywać i wyświetlać w zasobie Events interfejsu Calendar API.

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

Aby wyświetlić listę zdarzeń stanu, użyj metody events.list, określają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ść, i zapoznaj się z odpowiednim polem, aby uzyskać szczegółowe informacje o stanie utworzonym przez użytkownika w Kalendarzu Google:

Subskrybuj zmiany dotyczące zdarzeń stanu

Zmiany w zdarzeniach stanu możesz zasubskrybować w zasobie Events interfejsu Calendar API.

Użyj metody events.watch, wskazując w polu eventTypes element calendarId kalendarza do zasubskrybowania i co najmniej jedną z tych wartości:

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

Tworzenie i aktualizowanie wydarzeń stanu w Kalendarzu

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, zdarzenie musi zawierać wymagane pola.

Utwórz czas skupienia

Aby utworzyć wydarzenie typu czas skupienia:

  • Ustaw eventType na 'focusTime'.
  • Uwzględnij pole focusTimeProperties.
  • W polu transparency ustaw wartość 'opaque'.
  • Ustaw w polach start i end zdarzenia zdarzenia czasowego (z określonymi godzinami rozpoczęcia i zakończenia).
    Czas skupienia nie może obejmować wydarzeń całodniowych.

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

Utwórz status Poza biurem

Aby utworzyć wydarzenie Poza biurem:

  • Ustaw eventType na 'outOfOffice'.
  • Uwzględnij pole outOfOfficeProperties.
  • W polu transparency ustaw wartość 'opaque'.
  • Ustaw w polach start i end zdarzenia zdarzenia czasowego (z określonymi godzinami rozpoczęcia i zakończenia).
    Wydarzenia poza biurem nie mogą być wydarzeniami całodniowymi.

Szczegółowe informacje o funkcjach znajdziesz w artykule Wyświetlanie informacji o nieobecności w biurze.

Utwórz lokalizację 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'.
  • W polach start i end zdarzenia ustaw jedno z tych pól:

    • Wydarzenie ograniczone czasowo (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 1 dzień.

    Całodniowe wydarzenia w lokalizacji miejsca pracy nie mogą obejmować kilku dni, a wydarzenia zaplanowane mogą obejmować kilka dni.

Te pola są opcjonalne, ale zalecane, by zwiększyć wygodę użytkowników podczas wstawiania officeLocation:

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

Szczegółowe informacje o funkcjach 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ć pokrywające się wydarzenia w lokalizacji miejsca pracy

Użytkownik może mieć w kalendarzu wiele wydarzeń w lokalizacji miejsca pracy, które się nakładają. Oznacza to, że w danym czasie może być ustawione wiele lokalizacji miejsca pracy. Jeśli użytkownik może wyświetlić tylko jedną lokalizację, powinna ona być wyświetlana konsekwentnie w wielu aplikacjach. Podczas wybierania zdarzeń do wyświetlenia postępuj zgodnie z tymi wskazówkami:

  • Zdarzenia czasowe mają pierwszeństwo przed wydarzeniami całodniowymi.
  • Pojedyncze wydarzenia mają pierwszeństwo przed wydarzeniami cyklicznych i ich wyjątkami.
  • Zdarzenia, które zaczynają się później, mają pierwszeństwo przed tymi, które zaczynają się wcześniej.
  • Zdarzenia o krótszym czasie trwania mają pierwszeństwo przed zdarzeniami o dłuższym czasie trwania.
  • Nowsze wydarzenia mają pierwszeństwo przed tymi utworzonymi wcześniej.
  • Częściowo pokrywające się wydarzenia powinny być wyświetlane jako 2 różne wydarzenia z własną lokalizacją miejsca pracy.

Tworzenie zdarzeń stanu w Google Apps Script

Google Apps Script to oparty na języku JavaScript język obsługi skryptów w chmurze, który umożliwia tworzenie aplikacji biznesowych zintegrowanych z Google Workspace. Skrypty tworzy się w edytorze kodu działającym w przeglądarce, a są przechowywane i uruchamiane na serwerach Google. Przeczytaj też krótkie wprowadzenie do Google Apps Script, aby zacząć używać Apps Script do wysyłania żądań do interfejsu Google Calendar API.

Poniżej znajdziesz instrukcje zarządzania zdarzeniami stanu przy użyciu interfejsu Google Calendar API jako usługi zaawansowanej w Google Apps Script. Pełną listę zasobów i metod interfejsu Google Calendar API znajdziesz w dokumentacji referencyjnej.

Tworzenie i konfigurowanie skryptu

  1. Aby utworzyć skrypt, wejdź na script.google.com/create.
  2. W panelu po lewej stronie obok opcji 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. Metody i klasy dostępne w interfejsie API można wyświetlić za pomocą słowa kluczowego Kalendarz w edytorze.

(Opcjonalnie) Aktualizowanie projektu Google Cloud

Każdy projekt Google Apps Script ma powiązany projekt Google Cloud. Twój skrypt może używać domyślnego projektu utworzonego automatycznie przez Google Apps Script. Jeśli chcesz użyć niestandardowego projektu Google Cloud, zaktualizuj projekt powiązany ze skryptem, wykonując opisane niżej czynności.

  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 należącego do programu podglądu dla programistów i kliknij Ustaw projekt.
  4. Po lewej stronie kliknij Edytor , aby wrócić do edytora kodu.

Dodaj kod do skryptu

Poniższy przykładowy kod pokazuje, jak tworzyć, odczytywać i wyświetlać zdarzenia stanu 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/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. W menu nad edytorem kodu wybierz funkcję do uruchomienia i kliknij Uruchom.
  2. Przy pierwszym uruchomieniu wyświetli się prośba o autoryzację dostępu. Przejrzyj i zezwól Apps Script na dostęp do kalendarza.
  3. Wyniki wykonywania skryptu możesz sprawdzić w Dzienniku wykonywania u dołu okna.