Erweiterter Kalenderdienst

Script für den Zugriff auf und die Änderung von Nutzerkalendern mit zusätzlichen Funktionen.

Mit dem erweiterten Kalenderdienst können Sie die öffentliche Google Calendar API in Google Apps Script verwenden. Ähnlich wie beim integrierten Kalenderdienst von Apps Script können mit dieser API Skripts auf den Google-Kalender des Nutzers zugreifen und ihn ändern, einschließlich zusätzlicher Kalender, die der Nutzer abonniert hat. In den meisten Fällen ist der integrierte Dienst einfacher zu verwenden. Dieser erweiterte Dienst bietet jedoch einige zusätzliche Funktionen, z. B. das Festlegen der Hintergrundfarbe für einzelne Ereignisse.

Dies ist ein erweiterter Dienst, der vor der Verwendung aktiviert werden muss.

Referenz

Ausführliche Informationen zu diesem Dienst finden Sie in der Referenzdokumentation für die öffentliche Calendar API. Wie alle erweiterten Dienste in Apps Script verwendet der erweiterte Kalenderdienst dieselben Objekte, Methoden und Parameter wie die öffentliche API. Weitere Informationen finden Sie unter Methodensignaturen ermitteln.

Informationen zum Melden von Problemen und zu Supportoptionen finden Sie im Google Kalender-Supportleitfaden.

HTTP-Anfrageheader

Der erweiterte Kalenderdienst kann die HTTP-Anfrageheader If-Match und If-None-Match akzeptieren. Weitere Informationen finden Sie in der Referenzdokumentation.

Beispielcode

Im folgenden Beispielcode wird Version 3 der API verwendet.

Ereignisse erstellen

Das folgende Beispiel zeigt, wie Sie ein Ereignis im Standardkalender des Nutzers erstellen.

advanced/calendar.gs
/**
 * Creates an event in the user's default calendar.
 * @see https://developers.google.com/calendar/api/v3/reference/events/insert
 */
function createEvent() {
  const calendarId = "primary";
  const start = getRelativeDate(1, 12);
  const end = getRelativeDate(1, 13);
  // event details for creating event.
  let event = {
    summary: "Lunch Meeting",
    location: "The Deli",
    description: "To discuss our plans for the presentation next week.",
    start: {
      dateTime: start.toISOString(),
    },
    end: {
      dateTime: end.toISOString(),
    },
    attendees: [
      { email: "gduser1@workspacesample.dev" },
      { email: "gduser2@workspacesample.dev" },
    ],
    // Red background. Use Calendar.Colors.get() for the full list.
    colorId: 11,
  };
  try {
    // call method to insert/create new event in provided calandar
    event = Calendar.Events.insert(event, calendarId);
    console.log(`Event ID: ${event.id}`);
  } catch (err) {
    console.log("Failed with error %s", err.message);
  }
}

/**
 * Helper function to get a new Date object relative to the current date.
 * @param {number} daysOffset The number of days in the future for the new date.
 * @param {number} hour The hour of the day for the new date, in the time zone
 *     of the script.
 * @return {Date} The new date.
 */
function getRelativeDate(daysOffset, hour) {
  const date = new Date();
  date.setDate(date.getDate() + daysOffset);
  date.setHours(hour);
  date.setMinutes(0);
  date.setSeconds(0);
  date.setMilliseconds(0);
  return date;
}

Kalender auflisten

Das folgende Beispiel zeigt, wie Sie Details zu den Kalendern abrufen, die in der Kalenderliste des Nutzers angezeigt werden.

advanced/calendar.gs
/**
 * Lists the calendars shown in the user's calendar list.
 * @see https://developers.google.com/calendar/api/v3/reference/calendarList/list
 */
function listCalendars() {
  let calendars;
  let pageToken;
  do {
    calendars = Calendar.CalendarList.list({
      maxResults: 100,
      pageToken: pageToken,
    });
    if (!calendars.items || calendars.items.length === 0) {
      console.log("No calendars found.");
      return;
    }
    // Print the calendar id and calendar summary
    for (const calendar of calendars.items) {
      console.log("%s (ID: %s)", calendar.summary, calendar.id);
    }
    pageToken = calendars.nextPageToken;
  } while (pageToken);
}

Ereignisse auflisten

Das folgende Beispiel zeigt, wie die nächsten zehn anstehenden Termine im Standardkalender des Nutzers aufgelistet werden.

advanced/calendar.gs
/**
 * Lists the next 10 upcoming events in the user's default calendar.
 * @see https://developers.google.com/calendar/api/v3/reference/events/list
 */
function listNext10Events() {
  const calendarId = "primary";
  const now = new Date();
  const events = Calendar.Events.list(calendarId, {
    timeMin: now.toISOString(),
    singleEvents: true,
    orderBy: "startTime",
    maxResults: 10,
  });
  if (!events.items || events.items.length === 0) {
    console.log("No events found.");
    return;
  }
  for (const event of events.items) {
    if (event.start.date) {
      // All-day event.
      const start = new Date(event.start.date);
      console.log("%s (%s)", event.summary, start.toLocaleDateString());
      continue;
    }
    const start = new Date(event.start.dateTime);
    console.log("%s (%s)", event.summary, start.toLocaleString());
  }
}

Ereignisse bedingt ändern

Das folgende Beispiel zeigt, wie ein Kalendertermin mit dem Header If-Match bedingt aktualisiert wird. Das Skript erstellt ein neues Ereignis, wartet 30 Sekunden und aktualisiert das Ereignis dann nur, wenn sich seit der Erstellung des Ereignisses keine Ereignisdetails geändert haben.

advanced/calendar.gs
/**
 * Creates an event in the user's default calendar, waits 30 seconds, then
 * attempts to update the event's location, on the condition that the event
 * has not been changed since it was created.  If the event is changed during
 * the 30-second wait, then the subsequent update will throw a 'Precondition
 * Failed' error.
 *
 * The conditional update is accomplished by setting the 'If-Match' header
 * to the etag of the new event when it was created.
 */
function conditionalUpdate() {
  const calendarId = "primary";
  const start = getRelativeDate(1, 12);
  const end = getRelativeDate(1, 13);
  let event = {
    summary: "Lunch Meeting",
    location: "The Deli",
    description: "To discuss our plans for the presentation next week.",
    start: {
      dateTime: start.toISOString(),
    },
    end: {
      dateTime: end.toISOString(),
    },
    attendees: [
      { email: "gduser1@workspacesample.dev" },
      { email: "gduser2@workspacesample.dev" },
    ],
    // Red background. Use Calendar.Colors.get() for the full list.
    colorId: 11,
  };
  event = Calendar.Events.insert(event, calendarId);
  console.log(`Event ID: ${event.getId()}`);
  // Wait 30 seconds to see if the event has been updated outside this script.
  Utilities.sleep(30 * 1000);
  // Try to update the event, on the condition that the event state has not
  // changed since the event was created.
  event.location = "The Coffee Shop";
  try {
    event = Calendar.Events.update(
      event,
      calendarId,
      event.id,
      {},
      { "If-Match": event.etag },
    );
    console.log(`Successfully updated event: ${event.id}`);
  } catch (e) {
    console.log(`Fetch threw an exception: ${e}`);
  }
}

Ereignis bedingt abrufen

Das folgende Beispiel zeigt, wie ein Kalenderereignis mithilfe des Headers If-None-Match bedingt abgerufen wird. Das Skript erstellt ein neues Ereignis und fragt dann 30 Sekunden lang nach Änderungen ab. Jedes Mal, wenn sich das Ereignis ändert, wird die neue Version abgerufen.

advanced/calendar.gs
/**
 * Creates an event in the user's default calendar, then re-fetches the event
 * every second, on the condition that the event has changed since the last
 * fetch.
 *
 * The conditional fetch is accomplished by setting the 'If-None-Match' header
 * to the etag of the last known state of the event.
 */
function conditionalFetch() {
  const calendarId = "primary";
  const start = getRelativeDate(1, 12);
  const end = getRelativeDate(1, 13);
  let event = {
    summary: "Lunch Meeting",
    location: "The Deli",
    description: "To discuss our plans for the presentation next week.",
    start: {
      dateTime: start.toISOString(),
    },
    end: {
      dateTime: end.toISOString(),
    },
    attendees: [
      { email: "gduser1@workspacesample.dev" },
      { email: "gduser2@workspacesample.dev" },
    ],
    // Red background. Use Calendar.Colors.get() for the full list.
    colorId: 11,
  };
  try {
    // insert event
    event = Calendar.Events.insert(event, calendarId);
    console.log(`Event ID: ${event.getId()}`);
    // Re-fetch the event each second, but only get a result if it has changed.
    for (let i = 0; i < 30; i++) {
      Utilities.sleep(1000);
      event = Calendar.Events.get(
        calendarId,
        event.id,
        {},
        { "If-None-Match": event.etag },
      );
      console.log(`New event description: ${event.start.dateTime}`);
    }
  } catch (e) {
    console.log(`Fetch threw an exception: ${e}`);
  }
}

Termine synchronisieren

Das folgende Beispiel zeigt, wie Sie Ereignisse mithilfe von Synchronisierungstokens abrufen. Wenn Sie ein Synchronisierungstoken in eine Anfrage für einen erweiterten Kalenderdienst einfügen, enthält die resultierende Antwort nur Elemente, die sich seit der Generierung des Tokens geändert haben. So kann die Verarbeitung effizienter erfolgen. Weitere Informationen zum Synchronisierungsprozess finden Sie unter Ressourcen effizient synchronisieren.

Im folgenden Beispiel wird dieselbe getRelativeDate(daysOffset, hour)-Methode verwendet, die in den vorherigen Beispielen definiert wurde.

advanced/calendar.gs
/**
 * Retrieve and log events from the given calendar that have been modified
 * since the last sync. If the sync token is missing or invalid, log all
 * events from up to a month ago (a full sync).
 *
 * @param {string} calendarId The ID of the calender to retrieve events from.
 * @param {boolean} fullSync If true, throw out any existing sync token and
 *        perform a full sync; if false, use the existing sync token if possible.
 */
function logSyncedEvents(calendarId, fullSync) {
  const properties = PropertiesService.getUserProperties();
  const options = {
    maxResults: 100,
  };
  const syncToken = properties.getProperty("syncToken");
  if (syncToken && !fullSync) {
    options.syncToken = syncToken;
  } else {
    // Sync events up to thirty days in the past.
    options.timeMin = getRelativeDate(-30, 0).toISOString();
  }
  // Retrieve events one page at a time.
  let events;
  let pageToken;
  do {
    try {
      options.pageToken = pageToken;
      events = Calendar.Events.list(calendarId, options);
    } catch (e) {
      // Check to see if the sync token was invalidated by the server;
      // if so, perform a full sync instead.
      if (
        e.message === "Sync token is no longer valid, a full sync is required."
      ) {
        properties.deleteProperty("syncToken");
        logSyncedEvents(calendarId, true);
        return;
      }
      throw new Error(e.message);
    }
    if (events.items && events.items.length === 0) {
      console.log("No events found.");
      return;
    }
    for (const event of events.items) {
      if (event.status === "cancelled") {
        console.log("Event id %s was cancelled.", event.id);
        return;
      }
      if (event.start.date) {
        const start = new Date(event.start.date);
        console.log("%s (%s)", event.summary, start.toLocaleDateString());
        return;
      }
      // Events that don't last all day; they have defined start times.
      const start = new Date(event.start.dateTime);
      console.log("%s (%s)", event.summary, start.toLocaleString());
    }
    pageToken = events.nextPageToken;
  } while (pageToken);
  properties.setProperty("syncToken", events.nextSyncToken);
}