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 ihren HTTP-Schnittstellen herstellen. Erweiterte Dienste sind im Grunde schlanke Wrapper für diese Google APIs. Sie funktionieren ähnlich wie die integrierten Dienste von Apps Script, beispielsweise bieten sie die automatische Vervollständigung und Apps Script verarbeitet den Autorisierungsvorgang automatisch. Sie müssen jedoch einen erweiterten Dienst aktivieren, bevor Sie ihn in einem Skript verwenden können.

Welche Google APIs als erweiterte Dienste verfügbar sind, können Sie dem Abschnitt Erweiterte Google-Dienste in der Referenz entnehmen. 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 oder einfach direkt mit UrlFetch auf die APIs zugreifen.

Wenn Sie die erweiterte Dienstmethode verwenden, verarbeitet Apps Script den Autorisierungsvorgang und unterstützt die automatische Vervollständigung. Sie müssen jedoch zuerst den erweiterten Dienst aktivieren. Außerdem bieten einige erweiterte Dienste nur einen Teil der in der API verfügbaren Funktionen.

Wenn Sie die Methode UrlFetch verwenden, um direkt auf die API zuzugreifen, behandeln Sie die Google API im Wesentlichen als externe API. Bei dieser Methode können alle Aspekte der API genutzt werden. Sie müssen die API-Autorisierung jedoch selbst vornehmen. 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 sollte nur verwendet werden, wenn der erweiterte Dienst nicht die benötigten Funktionen bietet.

Voraussetzungen

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

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

  2. Die API, die dem erweiterten Dienst entspricht, muss im von Ihrem Skript verwendeten Cloud Platform-Projekt aktiviert sein.

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

    Wenn Ihr Skriptprojekt ein Standard-GCP-Projekt 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 vornehmen zu können.

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 bei der automatischen Vervollständigung verfügbar.

Ermittlung von Methodensignaturen

Erweiterte Dienste verwenden im Allgemeinen 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 Skripteditors 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 Medienuploadanhang. Einige erweiterte Dienste können auch bestimmte HTTP-Anfrageheader akzeptieren, z. B. den erweiterten Dienst von Google Kalender.

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

  1. Der Anfragetext (normalerweise eine Ressource) als JavaScript-Objekt.
  2. Pfad oder erforderliche Parameter als einzelne Argumente.
  3. Der Media-Upload-Anhang als Blob-Argument.
  4. Optionale Parameter als JavaScript-Objekt, das Parameternamen Werten zuordnet.
  5. HTTP-Anfrageheader als JavaScript-Objekt, das Headerwerte Header-Werten zuordnet.

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

Es gibt jedoch einige besondere Ausnahmen:

  • Bei Methoden, die einen Medienupload akzeptieren, wird der Parameter uploadType automatisch festgelegt.
  • Die Methoden mit dem Namen delete in der Google API haben in Apps Script den Namen remove, da delete ein reserviertes Wort in JavaScript ist.
  • Wenn ein erweiterter Dienst so konfiguriert ist, dass er HTTP-Anfrageheader akzeptiert, und Sie ein Anfrageheader-JavaScript-Objekt festlegen, müssen Sie auch das optionale JavaScript-Objekt auf Parameter festlegen. Verwenden Sie dazu ein leeres Objekt, wenn Sie optionale Parameter verwenden.

Unterstützung erweiterter Dienste

Erweiterte Dienste sind schlanke Wrapper, mit denen eine Google API in Apps Script verwendet werden kann. Daher stellt jedes Problem, das bei der Verwendung auftritt, normalerweise ein Problem mit der zugrunde liegenden API und nicht mit Apps Script selbst dar.

Wenn bei der Verwendung eines erweiterten Dienstes ein Problem auftritt, sollten Sie es mithilfe der Anleitung für die zugrunde liegende API melden. Links zu dieser Supportanleitung finden Sie in der jeweiligen Anleitung für erweiterte Dienste im Abschnitt Referenz für Apps Script.