Termine zu Fokuszeit, Abwesenheit und Arbeitsort verwalten

Auf dieser Seite wird beschrieben, wie Sie mit der Google Calendar API Ereignisse erstellen, die den Status von Google Kalender-Nutzern anzeigen. Statusereignisse beschreiben, wo sich Nutzer befinden oder was sie tun, z. B. ob sie in einer Fokuszeit sind, nicht im Büro oder an einem bestimmten Ort arbeiten.

In Google Kalender können Nutzer Fokuszeit-, Abwesenheits- und Arbeitsorte erstellen, um ihren eigenen 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 Ruhezeit in Google Kalender verwenden und Arbeitsort für Nutzer aktivieren oder deaktivieren.

Kalenderstatusereignisse lesen und auflisten

In der Events-Ressource der Calendar API können Sie Kalenderstatusereignisse lesen und auflisten.

Verwenden Sie die Methode events.get, um ein Statusereignis zu lesen, und geben Sie dabei 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. Im entsprechenden Feld finden Sie Details zum Status, den der Nutzer in Google Kalender erstellt hat:

Änderungen an Statusereignissen abonnieren

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

Verwende die Methode events.watch und gib den calendarId des zu abonnierenden Kalenders und einen oder mehrere der folgenden Werte in das Feld eventTypes ein:

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

Kalenderstatusereignisse erstellen und aktualisieren

Dazu erstellen Sie mit der Methode events.insert eine Instanz der Ressource Events und legen die Pflichtfelder für den Ereignistyp fest.

Wenn du das Statusereignis mit der Methode events.update aktualisierst, müssen die erforderlichen Felder im Ereignis beibehalten werden.

Fokuszeit erstellen

So erstellen Sie einen Fokuszeit-Termin:

  • Legen Sie eventType auf 'focusTime' fest.
  • Fügen Sie das Feld focusTimeProperties ein.
  • Setzen Sie das Feld transparency auf 'opaque'.
  • Legen Sie die Felder start und end des Ereignisses als zeitgesteuertes Ereignis fest (mit Start- und Endzeit).
    Fokuszeiten können keine ganztägigen Termine sein.

Weitere Informationen zur Funktion finden Sie unter Fokuszeit in Google Kalender verwenden.

Abwesenheitsnotiz erstellen

So erstellen Sie ein Abwesenheitsereignis:

  • Legen Sie eventType auf 'outOfOffice' fest.
  • Fügen Sie das Feld outOfOfficeProperties ein.
  • Setzen Sie das Feld transparency auf 'opaque'.
  • Legen Sie die Felder start und end des Ereignisses als zeitgesteuertes Ereignis fest (mit Start- und Endzeit).
    Außer-Haus-Termine können keine ganztägigen Termine sein.

Weitere Informationen zu den Features finden Sie unter Abwesenheit anzeigen.

Arbeitsort erstellen

So erstellen Sie ein Ereignis für den Arbeitsort:

  • Legen Sie eventType auf '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 angegebenem Beginn und Ende)
    • Ein ganztägiges Ereignis (mit Start- und Enddatum), das genau einen Tag dauert.

    Ganztägige Ereignisse an einem Arbeitsort können nicht mehrere Tage umfassen, zeitgebundene Ereignisse hingegen schon.

Die folgenden Felder sind optional, werden aber empfohlen, um beim Einfügen eines officeLocation eine optimale Nutzererfahrung zu bieten:

Das Erstellen und Aktualisieren von Ereignissen am Arbeitsort über die Batchendpunkte wird nicht unterstützt.

Weitere Informationen zu den Funktionen finden Sie unter Arbeitszeit und -ort festlegen und Arbeitsort für Nutzer aktivieren oder deaktivieren.

Überlappende Ereignisse für den Arbeitsort anzeigen

Ein Nutzer kann gleichzeitig mehrere Termine für seinen Arbeitsort in seinem Kalender haben, die sich überschneiden. Das bedeutet, dass für eine bestimmte Zeit mehrere Arbeitsort-Einträge festgelegt sein können. Wenn Nutzern nur ein einziger Standort angezeigt werden kann, sollte dieser Standort in mehreren Anwendungen einheitlich angezeigt werden. Beachten Sie dabei die folgenden Richtlinien, um das anzuzeigende Ereignis auszuwählen:

  • Termine mit Uhrzeit haben Vorrang vor ganztägigen Terminen.
  • Einzelne Ereignisse haben Vorrang vor wiederkehrenden Ereignissen und ihren Ausnahmen.
  • Ereignisse, die später beginnen, haben Vorrang vor Ereignissen, die früher beginnen.
  • Ereignisse mit kürzerer Dauer haben Vorrang vor Ereignissen mit längerer Dauer.
  • Kürzlich erstellte Ereignisse haben Vorrang vor Ereignissen, die früher erstellt wurden.
  • Teilweise überlappende Ereignisse sollten als zwei verschiedene Ereignisse mit jeweils einem eigenen Arbeitsstandort 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 in Google Workspace eingebunden werden. Scripts werden in einem browserbasierten Code-Editor entwickelt und auf den Google-Servern gespeichert und ausgeführt. Informationen zur Verwendung von Apps Script zum Senden von Anfragen an die Google Calendar API finden Sie in der Kurzanleitung zu Google Apps Script.

In der folgenden Anleitung wird beschrieben, wie Sie Statusereignisse mit der Google Calendar API als erweiterten Dienst in Google Apps Script verwalten. Eine vollständige Liste der Google Calendar API-Ressourcen und -Methoden finden Sie in der Referenzdokumentation.

Skript erstellen und einrichten

  1. Erstellen Sie ein Skript. Rufen Sie dazu script.google.com/create auf.
  2. Klicken Sie im linken Bereich neben Dienste auf „Dienst hinzufügen“ .
  3. Wählen Sie Google Calendar 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 mit dem Keyword Calendar 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 Script verknüpfte Projekt zu aktualisieren.

  1. Klicken Sie links im Editor auf „Projekteinstellungen“ .
  2. Klicken Sie unter Google Cloud Platform-Projekt (GCP-Projekt) auf Projekt ändern.
  3. Geben Sie die Projektnummer des Google Cloud-Projekts ein, das sich im Entwickler-Vorabprogramm befindet, und klicken Sie auf Projekt festlegen.
  4. Wählen Sie links „Editor“  aus, um zum Code-Editor 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 Codeeditor 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 oberhalb des Codeeditors die Funktion aus, die Sie ausführen möchten, aus dem Drop-down-Menü 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 darf, und erlauben Sie dies gegebenenfalls.
  3. Die Ergebnisse der Scriptausführung finden Sie im Ausführungslog, das unten im Fenster angezeigt wird.