Erweiterte Google-Dienste

Mit erweiterten Diensten in Apps Script können Sie mit weniger Aufwand als bei Verwendung der HTTP-Schnittstellen eine Verbindung zu bestimmten öffentlichen Google-APIs herstellen. Erweiterte Dienste sind Thin Wrappers um diese Google APIs. Sie funktionieren ähnlich wie die integrierten Dienste von Apps Script. Sie bieten beispielsweise die automatische Vervollständigung und Apps Script übernimmt den Autorisierungsablauf automatisch. Sie müssen jedoch einen erweiterten Dienst aktivieren, bevor Sie ihn in einem Skript verwenden können.

Erweiterte Dienste aktivieren

So verwenden Sie einen erweiterten Google-Dienst:

Schritt 1: Erweiterte Dienste aktivieren

Sie können einen erweiterten Dienst über den Apps Script-Editor oder durch Bearbeiten des Manifests aktivieren.

Methode A: Editor verwenden

1. Öffnen Sie das Apps Script-Projekt.
2. Klicken Sie links auf Editor code.
3. Klicken Sie links neben Dienste auf Dienst hinzufügen add.
4. Wählen Sie einen erweiterten Google-Dienst aus und klicken Sie auf Hinzufügen.

Methode B: Manifest verwenden

Sie können erweiterte Dienste aktivieren, indem Sie die Manifestdatei bearbeiten. Wenn Sie beispielsweise den erweiterten Google Drive-Dienst aktivieren möchten, fügen Sie dem Objekt dependencies das Feld enabledAdvancedServices hinzu:

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

Nachdem Sie einen erweiterten Dienst aktiviert haben, ist er in der automatischen Vervollständigung verfügbar.

Schritt 2: Google Cloud API aktivieren (nur Standard-Google Cloud-Projekte)

Wenn Sie ein standardmäßiges Google Cloud-Projekt verwenden, das automatisch von Apps Script erstellt wurde, können Sie diesen Schritt überspringen. Die API wird automatisch aktiviert, wenn Sie den Dienst in Schritt 1 hinzufügen.

Wenn Sie ein standardmäßiges Google Cloud-Projekt verwenden, müssen Sie die API, die dem erweiterten Dienst entspricht, auch manuell aktivieren. So aktivieren Sie die API manuell:

1. Öffnen Sie das Cloud-Projekt, das mit Ihrem Skript verknüpft ist, in der **Google Cloud Console**.

2. Klicken Sie oben in der Konsole in die Suchleiste und geben Sie einen Teil des Namens der API ein (z. B. „Calendar“). Klicken Sie dann auf den Namen, sobald er angezeigt wird.

3. Klicken Sie auf API aktivieren.

4. Schließen Sie die Google Cloud Console und kehren Sie zum Script-Editor zurück.

So werden Methodensignaturen ermittelt

Erweiterte Dienste verwenden in der Regel dieselben Objekte, Methodennamen und Parameter wie die entsprechenden öffentlichen APIs. Die Methodensignaturen werden jedoch für die Verwendung in Apps Script übersetzt. Die Autovervollständigungsfunktion des Script-Editors bietet in der Regel genügend Informationen für den Einstieg. In den folgenden Regeln wird jedoch erläutert, wie Apps Script eine Methodensignatur aus einer öffentlichen Google-API generiert.

Für Anfragen an Google-APIs können verschiedene Datentypen verwendet werden, darunter Pfadparameter, Abfrageparameter, ein Anfragetext oder ein Medien-Upload-Anhang. Einige erweiterte Dienste können auch bestimmte HTTP-Anfrageheader akzeptieren, z. B. der erweiterte Kalenderdienst.

Die entsprechende Methodensignatur in Google Apps Script hat die folgenden Argumente:

1. Der Anfragetext (in der Regel eine Ressource) als JavaScript-Objekt.
2. Pfad oder erforderliche Parameter als einzelne Argumente. Wenn für die Methode mehrere Pfadparameter erforderlich sind, werden sie in der Reihenfolge angezeigt, in der sie in der API-Endpunkt-URL aufgeführt sind.
3. Der Anhang für den Media-Upload als Blob-Argument.
4. Optionale Parameter (in der Regel Abfrageparameter) als JavaScript-Objekt, das Parameternamen Werten zuordnet.
5. HTTP-Anfrageheader als JavaScript-Objekt, das Headernamen Headerwerten zuordnet.

Wenn die Methode keine Elemente in einer bestimmten Kategorie hat, wird dieser Teil der Signatur weggelassen.

Es gibt einige besondere Ausnahmen:

• Bei Methoden, die einen Media-Upload akzeptieren, wird der Parameter uploadType automatisch festgelegt.
• Methoden mit dem Namen delete in der Google API heißen in Apps Script remove, da delete ein reserviertes Wort in JavaScript ist.
• Wenn ein erweiterter Dienst so konfiguriert ist, dass er HTTP-Anfrageheader akzeptiert, und Sie ein JavaScript-Objekt für Anfrageheader festlegen, müssen Sie auch das optionale JavaScript-Objekt für Parameter festlegen (auf ein leeres Objekt, wenn Sie keine optionalen Parameter verwenden).

Beispiel: Calendar.Events.insert

Angenommen, Sie möchten einen Kalendertermin erstellen. Die Dokumentation zur Google Calendar API enthält die entsprechende HTTP-Anfragestruktur:

• HTTP-Verb: POST
• Anfrage-URL: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events

• Anfragetext: Eine Event-Ressource.

• Abfrageparameter: sendUpdates, supportsAttachments usw.

In Apps Script wird die Methodensignatur durch Neuanordnung dieser Eingaben bestimmt:

1. Body: Die Ereignisressource (JavaScript-Objekt).
2. Pfad: calendarId (String).
3. Optionale Parameter: Die Abfrageparameter (JavaScript-Objekt).

Der resultierende Methodenaufruf sieht so aus:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

Erweiterte Dienste oder HTTP?

Jeder der erweiterten Google-Dienste ist mit einer öffentlichen Google-API verknüpft. In Apps Script können Sie über erweiterte Dienste oder durch direktes Senden der API-Anfragen mit UrlFetch auf diese APIs zugreifen.

Wenn Sie die Methode für erweiterte Dienste verwenden, übernimmt Apps Script den Autorisierungsablauf und bietet Unterstützung für die automatische Vervollständigung. Sie müssen den erweiterten Dienst jedoch aktivieren, bevor Sie ihn verwenden können.

Wenn Sie die UrlFetch-Methode verwenden, um direkt auf die API zuzugreifen, behandeln Sie die Google API im Grunde als externe API. Mit dieser Methode können alle Aspekte der API verwendet werden. Dazu müssen Sie jedoch die API-Autorisierung verwalten.

In der folgenden Tabelle werden die beiden Methoden verglichen:

Codevergleich

Die Codebeispiele zeigen den Unterschied im Komplexitätsgrad zwischen dem Erstellen eines Kalenderereignisses mit dem erweiterten Dienst und mit UrlFetchApp.

Erweiterter Service:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

UrlFetch (HTTP):

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

Wir empfehlen, nach Möglichkeit einen erweiterten Dienst zu verwenden und die UrlFetch-Methode nur dann, wenn der erweiterte Dienst nicht verfügbar ist oder nicht die benötigten Funktionen bietet.

Unterstützung für erweiterte Dienste

Da erweiterte Dienste Thin Wrappers um Google APIs sind, ist jedes Problem, das bei der Verwendung auftritt, in der Regel ein Problem mit der zugrunde liegenden API und nicht mit Apps Script.

Wenn Sie bei der Verwendung eines erweiterten Dienstes auf ein Problem stoßen, sollten Sie es gemäß der Supportanleitung für die zugrunde liegende API melden.