Erweiterte Google-Dienste

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

Informationen zu den Google APIs, die 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, stellen Sie einfach wie jede andere externe API eine Verbindung zu ihr her.

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 indem Sie die API-Anfragen 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 in der API verfügbaren Funktionen.

Wenn Sie die UrlFetch-Methode verwenden, um direkt auf die API zuzugreifen, behandeln Sie die Google API im Wesentlichen als externe API. Mit dieser Methode können alle Aspekte der API verwendet werden. Allerdings müssen Sie die API-Autorisierung selbst vornehmen. Außerdem müssen Sie alle erforderlichen Header erstellen und die API-Antworten parsen.

Im Allgemeinen ist es am einfachsten, nach Möglichkeit einen erweiterten Dienst zu nutzen. Die Methode UrlFetch sollte nur verwendet werden, wenn der erweiterte Dienst nicht die erforderliche Funktionalität bietet.

Voraussetzungen

Bevor Sie einen erweiterten Dienst verwenden können, müssen Sie die folgenden Anforderungen erfüllen:

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

  2. Achten Sie darauf, dass die API für den erweiterten Dienst im Cloud Platform-Projekt (GCP) aktiviert ist, das Ihr Skript verwendet.

    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 aufgefordert, auch den Nutzungsbedingungen von Google Cloud und Google APIs zuzustimmen.

    Wenn Ihr 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 verwenden 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.

So werden Methodensignaturen ermittelt

Erweiterte Dienste verwenden im Allgemeinen dieselben Objekte, Methodennamen und Parameter wie die entsprechenden öffentlichen APIs. Methodensignaturen werden jedoch für die Verwendung in Apps Script übersetzt. Die Funktion zur automatischen Vervollständigung des Skripteditors bietet in der Regel genügend Informationen für den Einstieg. Die folgenden Regeln erklären jedoch, wie Apps Script eine Methodensignatur aus einer öffentlichen Google API generiert.

Anfragen an Google APIs können eine Vielzahl verschiedener Datentypen annehmen, darunter Pfadparameter, Abfrageparameter, ein Anfragetext und/oder einen Medien-Uploadanhang. Einige erweiterte Dienste akzeptieren auch bestimmte HTTP-Anfrageheader, z. B. der erweiterte Kalenderdienst.

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

  1. Der Anfragetext (normalerweise eine Ressource) als JavaScript-Objekt.
  2. Pfad oder erforderliche Parameter als einzelne Argumente.
  3. Der Anhang des Medienuploads als Blob-Argument.
  4. Optionale Parameter als JavaScript-Objekt, das den Werten Parameternamen zuordnet
  5. HTTP-Anfrageheader als JavaScript-Objekt, das Headernamen den Headerwerten zuordnet

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

Es gibt einige besondere Ausnahmen, die Sie beachten sollten:

  • Bei Methoden, die einen Medienupload akzeptieren, wird der Parameter uploadType automatisch festgelegt.
  • Methoden mit dem Namen delete in der Google API werden in Apps Script als remove bezeichnet, da delete in JavaScript ein reserviertes Wort 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 (auf ein leeres Objekt, wenn Sie keine optionalen Parameter verwenden).

Support für erweiterte Dienste

Erweiterte Dienste sind nur schlanke Wrapper, die die Verwendung einer Google-APIs in Apps Script ermöglichen. Daher bezieht sich jedes Problem bei der Verwendung normalerweise auf die zugrunde liegende API, nicht auf die 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 dieser Supportanleitung finden Sie in jedem erweiterten Dienstleitfaden im Abschnitt Referenz zu Apps Script.