Erweiterte Google-Dienste

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

Informationen dazu, welche Google APIs als erweiterte Dienste verfügbar sind, finden Sie in der Referenz im Abschnitt Erweiterte Google-Dienste. Wenn Sie eine Google API verwenden möchten, die nicht als erweiterter Dienst verfügbar ist, können Sie wie jede andere externe API eine Verbindung zu ihr herstellen.

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 auf diese APIs zugreifen oder die API-Anfragen einfach direkt mit UrlFetch stellen.

Wenn Sie die erweiterte Dienstmethode verwenden, übernimmt Apps Script den Autorisierungsablauf und bietet Unterstützung für die automatische Vervollständigung. Sie müssen jedoch den erweiterten Dienst aktivieren, bevor Sie ihn verwenden können. Darüber hinaus bieten einige erweiterte Dienste nur einen Teil der Funktionen, die in der API verfügbar sind.

Wenn Sie die Methode UrlFetch für den direkten Zugriff auf die API verwenden, gilt die Google API im Wesentlichen als externe API. Mit dieser Methode können alle Aspekte der API genutzt werden. Allerdings müssen Sie die API-Autorisierung selbst übernehmen. Außerdem müssen Sie alle erforderlichen Header erstellen und die API-Antworten parsen.

Im Allgemeinen ist es am einfachsten, wenn möglich einen erweiterten Dienst zu verwenden, und die Methode UrlFetch nur dann zu verwenden, wenn der erweiterte Dienst nicht die erforderliche Funktionalität bietet.

Voraussetzungen

Bevor Sie einen erweiterten Dienst verwenden können, müssen folgende Voraussetzungen erfüllt sein:

  1. Sie müssen in Ihrem Skriptprojekt den erweiterten Dienst aktivieren.

  2. Achten Sie darauf, dass die API für den erweiterten Dienst in dem von Ihrem Skript verwendeten Cloud Platform-Projekt (GCP) aktiviert ist.

    Wenn Ihr Skriptprojekt ein GCP-Standardprojekt verwendet, das am oder nach dem 8. April 2019 erstellt wurde, wird die API automatisch aktiviert, nachdem Sie den erweiterten Dienst aktiviert und das Skriptprojekt gespeichert haben. Falls noch nicht geschehen, werden Sie möglicherweise außerdem aufgefordert, den Nutzungsbedingungen von Google Cloud und Google APIs zuzustimmen.

    Wenn das Skriptprojekt ein GCP-Standardprojekt oder ein älteres GCP-Standardprojekt verwendet, müssen Sie die entsprechende API des erweiterten Dienstes im GCP-Projekt manuell aktivieren. Sie benötigen Bearbeitungszugriff auf das GCP-Projekt, um diese Änderung vorzunehmen.

Weitere Informationen finden Sie unter Cloud Platform-Projekte.

Erweiterte Dienste aktivieren

So nutzen Sie einen erweiterten Google-Dienst:

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

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

Wie Methodensignaturen bestimmt werden

Erweiterte Dienste verwenden in der Regel dieselben Objekte, Methodennamen und Parameter wie die entsprechenden öffentlichen APIs, obwohl Methodensignaturen für die Verwendung in Apps Script übersetzt werden. Die Funktion zur automatischen Vervollständigung 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.

Anfragen an Google APIs können eine Vielzahl verschiedener Datentypen akzeptieren, darunter Pfadparameter, Abfrageparameter, ein Anfragetext und/oder ein Medien-Upload-Anhang. Einige erweiterte Dienste können auch bestimmte HTTP-Anfrageheader akzeptieren (z. B. der erweiterte Google Kalender-Dienst).

Die entsprechende Methodensignatur in Google Apps Script enthält die folgenden Argumente:

  1. Der Anfragetext (in der Regel eine Ressource) als JavaScript-Objekt.
  2. Pfad oder erforderliche Parameter als einzelne Argumente.
  3. Den Anhang für den Medienupload als Argument Blob.
  4. Optionale Parameter als JavaScript-Objekt, bei dem Parameternamen Werten zugeordnet werden.
  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 Medien-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 JavaScript-Objekt mit optionalen Parametern festlegen. Wenn Sie keine optionalen Parameter verwenden, muss dieses Objekt auf ein leeres Objekt gesetzt werden.

Support für erweiterte Dienste

Erweiterte Dienste sind einfache Wrapper, die die Verwendung von Google APIs in Apps Script ermöglichen. Daher werden Probleme, die während der Verwendung auftreten, normalerweise durch die zugrunde liegende API verursacht, nicht durch Apps Script selbst.

Wenn bei der Verwendung eines erweiterten Dienstes ein Problem auftritt, sollten Sie es mithilfe der Supportanleitung für die zugrunde liegende API melden. Links zu diesen Supportanleitungen finden Sie in jedem Leitfaden zu erweiterten Diensten im Abschnitt Referenz zu Apps Script.