Termine zu Fokuszeit, Abwesenheit und Arbeitsort verwalten

Auf dieser Seite wird erläutert, wie Sie mit der Google Kalender API Termine erstellen, die den Status von Google Kalender-Nutzern anzeigen. Statusereignisse beschreiben, wo sich Nutzer befinden oder was sie tun, z. B. ob sie sich in Fokuszeit befinden, abwesend sind oder von einem bestimmten Standort aus arbeiten.

In Google Kalender können Nutzer Fokuszeit-, Abwesenheits- und Arbeitsort-Termine erstellen, um ihren benutzerdefinierten Status und Standort anzugeben. Diese Funktionen sind nur für primäre Kalender und für einige Google Kalender-Nutzer verfügbar.

Weitere Informationen finden Sie unter Fokuszeit in Google Kalender verwenden und Arbeitsort für Nutzer aktivieren oder deaktivieren.

Kalenderstatusereignisse lesen und auflisten

Kalenderstatusereignisse können Sie in der Ressource Events der Kalender API lesen und auflisten.

Verwenden Sie zum Lesen eines Statusereignisses die Methode events.get und geben Sie den eventId des Ereignisses an.

Verwenden Sie zum Auflisten von Statusereignissen die Methode events.list und geben Sie einen oder mehrere der folgenden Werte im Feld eventTypes an:

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

Prüfen Sie dann in den zurückgegebenen Event-Objekten, ob das Feld eventType den angeforderten Wert enthält. Details zum vom Nutzer in Google Kalender erstellten Status finden Sie im entsprechenden Feld:

Änderungen an Statusereignissen abonnieren

Sie können Änderungen an Statusereignissen in der Ressource Events der Kalender API abonnieren.

Verwenden Sie die Methode events.watch und geben Sie den calendarId des zu abonnierenden Kalenders und einen oder mehrere der folgenden Werte im Feld eventTypes an:

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

Kalenderstatusereignisse erstellen und aktualisieren

Um ein Statusereignis zu erstellen, erstellen Sie mit der Methode events.insert eine Instanz der Ressource Events. Dabei legen Sie die erforderlichen Felder für den Ereignistyp fest.

Wenn Sie das Statusereignis mit der Methode events.update aktualisieren, müssen die Pflichtfelder für das Ereignis beibehalten werden.

Fokuszeit erstellen

So erstellen Sie einen Fokuszeit-Termin:

  • Legen Sie für eventType 'focusTime' fest.
  • Fügen Sie das Feld focusTimeProperties ein.
  • Setzen Sie das Feld transparency auf 'opaque'.
  • Lege die Felder start und end des Ereignisses auf ein zeitgesteuertes Ereignis fest, wobei die Start- und Endzeiten angegeben sind.
    Fokuszeiten können nicht ganztägige Termine sein.

Weitere Informationen finden Sie unter Fokuszeit in Google Kalender verwenden.

„Außer Haus“-Angabe erstellen

So erstellen Sie einen Abwesenheitstermin:

  • Legen Sie für eventType 'outOfOffice' fest.
  • Fügen Sie das Feld outOfOfficeProperties ein.
  • Setzen Sie das Feld transparency auf 'opaque'.
  • Lege die Felder start und end des Ereignisses auf ein zeitgesteuertes Ereignis fest, wobei die Start- und Endzeiten angegeben sind.
    Abwesenheitszeiten können keine ganztägigen Termine sein.

Weitere Informationen finden Sie unter Abwesenheit anzeigen.

Arbeitsort erstellen

So erstellen Sie einen Arbeitsort-Termin:

  • Legen Sie für eventType 'workingLocation' fest.
  • Fügen Sie das Feld workingLocationProperties ein.
  • Setzen Sie das Feld visibility auf 'public'.
  • Setzen Sie das Feld transparency auf 'transparent'.

  • Legen Sie für die Felder start und end des Ereignisses einen der folgenden Werte fest:

    • Ein zeitgesteuertes Ereignis (mit angegebenen Start- und Endzeiten);
    • Ein ganztägiges Ereignis (mit angegebenen Start- und Enddatum), das genau einen Tag umfasst.

    Ganztägige Arbeitsortereignisse können nicht mehrere Tage umfassen, zeitlich begrenzte Ereignisse jedoch schon.

Die folgenden Felder sind optional, werden aber für eine optimale Nutzererfahrung beim Einfügen eines officeLocation empfohlen:

Das Erstellen und Aktualisieren von Arbeitsstandortereignissen über die Batchendpunkte wird nicht unterstützt.

Informationen zum Feature finden Sie unter Arbeitszeit und -ort festlegen und Arbeitsort für Nutzer aktivieren oder deaktivieren.

Überschneidungen zwischen Arbeitsort-Ereignissen anzeigen

Ein Nutzer kann in seinem Kalender mehrere Termine mit Arbeitsorten haben, die sich überschneiden. Das bedeutet, dass für eine bestimmte Zeit mehrere Arbeitsorte festgelegt sein können. Wenn dem Nutzer nur ein einziger Standort angezeigt werden kann, sollte er diesen Standort in mehreren Anwendungen einheitlich angezeigt werden. Halten Sie sich dabei an die folgenden Richtlinien, um auszuwählen, welches Ereignis angezeigt werden soll:

  • Zeitlich begrenzte Ereignisse haben Vorrang vor ganztägigen Ereignissen.
  • Einzelne Ereignisse haben Vorrang vor wiederkehrenden Ereignissen und ihren Ausnahmen.
  • Termine, die später beginnen, haben Vorrang vor solchen, die früher beginnen.
  • Ereignisse mit einer kürzeren Dauer haben Vorrang vor solchen mit einer längeren Dauer.
  • Neuere Ereignisse haben Vorrang vor zuvor erstellten Ereignissen.
  • Sich teilweise überschneidende Ereignisse sollten als zwei verschiedene Ereignisse mit jeweils einem eigenen Arbeitsort angezeigt werden.

Statusereignisse in Google Apps Script erstellen

Google Apps Script ist eine JavaScript-basierte Cloud-Scriptsprache, mit der Sie Geschäftsanwendungen erstellen können, die sich in Google Workspace einbinden lassen. Skripts werden in einem browserbasierten Codeeditor entwickelt und auf den Google-Servern gespeichert und ausgeführt. In der Kurzanleitung zu Google Apps Script erfahren Sie, wie Sie mit Apps Script Anfragen an die Google Kalender API senden.

In der folgenden Anleitung wird beschrieben, wie Statusereignisse mithilfe der Google Kalender API als erweiterter Dienst in Google Apps Script verwaltet werden. Eine vollständige Liste der Google Kalender API-Ressourcen und -Methoden finden Sie in der Referenzdokumentation.

Skript erstellen und einrichten

  1. Rufen Sie script.google.com/create auf, um ein Skript zu erstellen.
  2. Klicken Sie im linken Bereich neben Dienste auf „Dienst hinzufügen“ .
  3. Wählen Sie Google Kalender API aus und klicken Sie auf Hinzufügen.
  4. Nach der Aktivierung wird die API im linken Bereich angezeigt. Verfügbare Methoden und Klassen in der API können im Editor mithilfe des Suchbegriffs Kalender aufgelistet werden.

(Optional) Google Cloud-Projekt aktualisieren

Jedem Google Apps Script-Projekt ist ein Google Cloud-Projekt zugeordnet. Ihr Skript kann das Standardprojekt verwenden, das von Google Apps Script automatisch erstellt wird. Wenn Sie ein benutzerdefiniertes Google Cloud-Projekt verwenden möchten, führen Sie die folgenden Schritte aus, um das mit Ihrem Skript verknüpfte Projekt zu aktualisieren.

  1. Klicken Sie links im Editor auf „Projekteinstellungen“ .
  2. Klicken Sie unter Google Cloud Platform-Projekt (GCP) auf Projekt ändern.
  3. Geben Sie die Projektnummer des Google Cloud-Projekts ein, das am Vorschauprogramm für Entwickler teilnimmt, und klicken Sie auf Projekt festlegen.
  4. Wählen Sie links „Editor“ aus, um zum Codeeditor zurückzukehren.

Code zum Script hinzufügen

Im folgenden Codebeispiel wird gezeigt, wie Sie Statusereignisse in Ihrem Hauptkalender erstellen, lesen und auflisten.

  1. Fügen Sie Folgendes in den Code-Editor ein.

    /** 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}`;
}

Codebeispiel ausführen

  1. Wählen Sie über dem Codeeditor die auszuführende Funktion im Drop-down-Menü aus und klicken Sie auf Ausführen.
  2. Bei der ersten Ausführung werden Sie aufgefordert, den Zugriff zu autorisieren. Prüfen Sie, ob Apps Script auf Ihren Kalender zugreifen kann, und erlauben Sie ihm.
  3. Sie können die Ergebnisse der Skriptausführung im Ausführungsprotokoll einsehen, das unten im Fenster angezeigt wird.