Termine zu Fokuszeit, Abwesenheit und Arbeitsort verwalten

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

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

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

Kalenderstatusereignisse lesen und auflisten

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

Verwenden Sie zum Lesen eines Statusereignisses die Methode events.get und geben Sie die 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 hat, und sehen Sie im entsprechenden Feld nach, um Details zum Status zu erhalten, der vom Nutzer in Google Kalender erstellt wurde:

Änderungen an Statusereignissen abonnieren

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

Verwenden Sie die Methode events.watch und geben Sie die calendarId des Kalenders an, den Sie abonnieren möchten, sowie einen oder mehrere der folgenden Werte im Feld eventTypes an:

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

Kalenderstatusereignisse erstellen und aktualisieren

Zum Erstellen eines Statusereignisses erstellen Sie eine Instanz der Ressource Events mit der Methode events.insert und legen die erforderlichen Felder für den Ereignistyp fest.

Wenn Sie das Statusereignis mit der Methode events.update aktualisieren, müssen die erforderlichen Felder beibehalten werden.

Fokuszeit erstellen

So erstellen Sie einen Fokuszeit-Termin:

  • Setze eventType auf 'focusTime'.
  • 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 Angabe von Start- und Endzeit).
    Fokuszeiten können keine ganztägigen Termine sein.

Weitere Informationen zu den Funktionen finden Sie im Hilfeartikel Fokuszeit in Google Kalender verwenden.

Abwesenheitsnotiz erstellen

So erstellen Sie ein Abwesenheitsereignis:

  • Setze eventType auf 'outOfOffice'.
  • 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 Angabe von Start- und Endzeit).
    Außer-Haus-Termine können nicht ganztägig sein.

Weitere Informationen zu den Funktionen finden Sie unter Zeigen, wenn Sie nicht im Büro sind.

Arbeitsort erstellen

So erstellen Sie ein Arbeitsort-Ereignis:

  • Setze eventType auf 'workingLocation'.
  • 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 zeitlich begrenztes Ereignis (mit Angabe von Start- und Endzeit);
    • Ein ganztägiges Ereignis (mit angegebenem Start- und Enddatum), das genau einen Tag umfasst.

    Ganztägige Arbeitsort-Ereignisse können sich nicht über mehrere Tage erstrecken, Ereignisse mit Zeitangabe schon.

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

Das Erstellen und Aktualisieren von Arbeitsort-Ereignissen über die Batch-Endpunkte 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 Arbeitsort-Ereignisse anzeigen

Ein Nutzer kann mehrere Arbeitsorttermine in seinem Kalender haben, die sich überschneiden. Das bedeutet, dass für einen bestimmten Zeitpunkt mehrere Arbeitsorte festgelegt sein können. Wenn dem Nutzer nur ein einziger Standort angezeigt werden kann, sollte dieser Standort in mehreren Anwendungen einheitlich angezeigt werden. Beachten Sie dabei die folgenden Richtlinien, um das richtige Ereignis auszuwählen:

  • Termine mit Uhrzeit haben Vorrang vor ganztägigen Terminen.
  • Einzelne Termine haben Vorrang vor wiederkehrenden Terminen und ihren Ausnahmen.
  • Termine, die später beginnen, haben Vorrang vor Terminen, die früher beginnen.
  • Ereignisse mit kürzeren Zeiträumen haben Vorrang vor Ereignissen mit längeren Zeiträumen.
  • Vorrang haben Ereignisse, die vor Kurzem erstellt wurden.
  • Teilweise überschneidende Termine sollten als zwei verschiedene Termine mit jeweils eigenem 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 in Google Workspace eingebunden werden. Scripts werden in einem browserbasierten Code-Editor entwickelt und auf den Servern von Google gespeichert und ausgeführt. Google Apps Script-Kurzanleitung, um mit Apps Script Anfragen an die Google Kalender API zu senden.

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. 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 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 mit dem Keyword Calendar im Editor aufgerufen werden.

(Optional) Google Cloud-Projekt aktualisieren

Jedes Google Apps Script-Projekt ist mit einem Google Cloud-Projekt verknüpft. Ihr Skript kann das Standardprojekt verwenden, das von Google Apps Script automatisch erstellt wird. Wenn Sie ein benutzerdefiniertes Google Cloud-Projekt verwenden möchten, gehen Sie so vor, 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) auf Projekt wechseln.
  3. Geben Sie die Projektnummer des Google Cloud-Projekts ein, das am Developer Preview-Programm teilnimmt, und klicken Sie auf Projekt festlegen.
  4. Wählen Sie auf der linken Seite „Editor“  aus, um zum Code-Editor zurückzukehren.

Code zum Skript hinzufügen

Das folgende Codebeispiel zeigt, wie Sie Statusereignisse in Ihrem primären Kalender 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/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}`;
}

Codebeispiel ausführen

  1. Wählen Sie über dem Code-Editor die auszuführende Funktion aus dem 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 darf, und erteilen Sie gegebenenfalls die Berechtigung.
  3. Die Ergebnisse der Scriptausführung können Sie im Ausführungslog unten im Fenster ansehen.