Termine zu Fokuszeit, Abwesenheit und Arbeitsort verwalten

Auf dieser Seite wird erläutert, wie Sie mit der Google Calendar 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 der Fokuszeit befinden, abwesend sind oder von einem bestimmten Ort aus arbeiten.

In Google Kalender können Nutzer Fokuszeit-, Abwesenheits- und Arbeitsorttermine 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 unter 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 die events.get Methode, um ein Statusereignis zu lesen, und geben Sie die eventId des Ereignisses an.

Verwenden Sie die events.list Methode, um Statusereignisse aufzulisten, und geben Sie im Feld eventTypes einen oder mehrere der folgenden Werte an:

'focusTime'
'outOfOffice'
'workingLocation'

Prüfen Sie dann in den zurückgegebenen Event Objekten, ob das eventType Feld den gewünschten 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 events.watch Methode, geben Sie die calendarId des Kalenders an, den Sie abonnieren möchten, sowie einen oder mehrere der folgenden Werte im eventTypes Feld:

'focusTime'
'outOfOffice'
'workingLocation'

Kalenderstatusereignisse erstellen und aktualisieren

Wenn Sie ein Statusereignis erstellen möchten, erstellen Sie mit der events.insert Methode eine Instanz der Events Ressource und legen die erforderlichen Felder für den Ereignistyp fest.

Wenn Sie das Statusereignis mit der events.update Methode aktualisieren, muss das Ereignis die erforderlichen Felder beibehalten.

Fokuszeit erstellen

So erstellen Sie ein Fokuszeitereignis:

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

Weitere Informationen zu den Funktionen finden Sie unter Fokuszeit in Google Kalender.

Abwesenheit erstellen

So erstellen Sie ein Abwesenheitsereignis:

Setzen Sie eventType auf 'outOfOffice'.
Fügen Sie das outOfOfficeProperties Feld ein.
Setzen Sie das transparency Feld auf 'opaque'.
Legen Sie für die Felder start und end des Ereignisses ein zeitlich festgelegtes Ereignis fest (mit Angabe von Start- und Endzeit).
Abwesenheitsereignisse können keine ganztägigen Termine sein.

Weitere Informationen zu den Funktionen finden Sie unter Anzeigen, wenn Sie abwesend sind

Arbeitsort erstellen

So erstellen Sie ein Arbeitsortereignis:

Setzen Sie eventType auf 'workingLocation'.
Fügen Sie das workingLocationProperties Feld ein.
Setzen Sie das visibility Feld auf 'public'.
Setzen Sie das transparency Feld auf 'transparent'.
Legen Sie für die Felder start und end des Ereignisses Folgendes fest:
- Ein zeitlich festgelegtes Ereignis (mit Angabe von Start- und Endzeit)
- Ein ganztägiges Ereignis (mit Angabe von Start- und Enddatum), das genau einen Tag dauert
Ganztägige Arbeitsorttermine können nicht mehrere Tage umfassen, zeitlich festgelegte Termine jedoch schon.

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

workingLocationProperties.officeLocation.buildingId: Dies muss mit einer buildingId in der Ressourcendatenbank der Organisation übereinstimmen. So können Nutzer alle Kalenderfunktionen nutzen, z. B. Raumvorschläge.
workingLocationProperties.officeLocation.label: Dies ist das Label, das in den Google Kalender-Web- und Mobilclients angezeigt wird. Sie können Gebäude-IDs und Gebäudelabels mit der resources.buildings.list Methode abrufen.

Das Erstellen und Aktualisieren von Arbeitsortterminen ü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 Arbeitsorttermine anzeigen

Ein Nutzer kann mehrere Arbeitsorttermine gleichzeitig 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 Ort angezeigt werden kann, sollte dieser Ort in mehreren Anwendungen einheitlich angezeigt werden. Verwenden Sie dabei die folgenden Richtlinien, um auszuwählen, welches Ereignis angezeigt werden soll:

Zeitlich festgelegte Termine haben Vorrang vor ganztägigen Terminen.
Einmalige Termine haben Vorrang vor wiederkehrenden Terminen und deren Ausnahmen.
Termine, die später beginnen, haben Vorrang vor Terminen, die früher beginnen.
Termine mit kürzerer Dauer haben Vorrang vor Terminen mit längerer Dauer.
Kürzlich erstellte Termine haben Vorrang vor Terminen, die früher erstellt wurden.
Teilweise überlappende 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 Skriptsprache, mit der Sie Geschäftsanwendungen erstellen können, die in Google Workspace eingebunden werden. Skripts werden in einem browserbasierten Code-Editor entwickelt und auf den Servern von Google gespeichert und ausgeführt. Im Google Apps Script Schnellstart erfahren Sie, wie Sie mit Apps Script Anfragen an die Google Calendar API 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 Ressourcen und Methoden der Google Calendar API, finden Sie in der Referenzdokumentation.

Skript erstellen und einrichten

Erstellen Sie ein Skript unter script.google.com/create.
Klicken Sie im linken Bereich neben Dienste auf „Dienst hinzufügen“ .
Wählen Sie Google Calendar API aus und klicken Sie auf Hinzufügen.
Nach der Aktivierung wird die API im linken Bereich angezeigt. Verfügbare Methoden und Klassen in der API können mit dem Schlüsselwort Calendar im Editor aufgelistet werden.

(Optional) Google Cloud-Projekt aktualisieren

Jedes Google Apps Script-Projekt hat ein zugehöriges Google Cloud-Projekt. Ihr Skript kann das Standardprojekt verwenden, das automatisch von Google Apps Script 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.

Klicken Sie links im Editor auf „Projekteinstellungen“ .
Klicken Sie unter Google Cloud Platform-Projekt (GCP) auf Projekt wechseln.
Geben Sie die Projektnummer des Google Cloud-Projekts ein, das am Developer Preview-Programm teilnimmt, und klicken Sie auf Projekt festlegen.
Wählen Sie links „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.

Fügen Sie Folgendes in den Code-Editor ein:

primary ist ein Schlüsselwort für den Zugriff auf den primären Kalender des angemeldeten Nutzers. Wenn Sie Termine in einem anderen Kalender abrufen möchten, legen Sie den Parameter calendarId auf eine E‑Mail-Adresse fest. So können Sie Statusereignisse in den Kalendern anderer Nutzer lesen, auf die Sie mindestens Zugriff auf die Verfügbarkeit haben. Sekundäre Kalender können keine Statusereignisse haben.

/** 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

Wählen Sie über dem Code-Editor im Drop-down-Menü die auszuführende Funktion aus und klicken Sie auf Ausführen.
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 den Zugriff.
Die Ergebnisse der Skriptausführung können Sie im Ausführungsprotokoll unten im Fenster sehen.

Termine zu Fokuszeit, Abwesenheit und Arbeitsort verwalten Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Kalenderstatusereignisse lesen und auflisten

Änderungen an Statusereignissen abonnieren

Kalenderstatusereignisse erstellen und aktualisieren

Fokuszeit erstellen

Abwesenheit erstellen

Arbeitsort erstellen

Überlappende Arbeitsorttermine anzeigen

Statusereignisse in Google Apps Script erstellen

Skript erstellen und einrichten

(Optional) Google Cloud-Projekt aktualisieren

Code zum Skript hinzufügen

Codebeispiel ausführen

Termine zu Fokuszeit, Abwesenheit und Arbeitsort verwalten