Erweiterte Google-Dienste

Mit den erweiterten Diensten in Apps Script können erfahrene Entwickler mit weniger Aufwand als bei Verwendung der HTTP-Schnittstellen eine Verbindung zu bestimmten öffentlichen Google-APIs herstellen. Erweiterte Dienste sind im Grunde 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.

Welche Google APIs als erweiterte Dienste verfügbar sind, sehen 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 bei jeder anderen externen API eine Verbindung 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 die API-Anfragen einfach direkt mit UrlFetch stellen.

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 aktivieren, bevor Sie ihn verwenden können. 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 Grunde 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 verwenden und die Methode UrlFetch nur dann, wenn der erweiterte Dienst nicht die benötigte Funktionalität bietet.

Voraussetzungen

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

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

  2. Die API, die dem erweiterten Dienst entspricht, muss im Cloud Platform-Projekt (GCP) aktiviert sein, das von Ihrem Skript verwendet wird.

    Wenn in Ihrem Skriptprojekt ein standardmäßiges GCP-Projekt verwendet wird, 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 von Google Cloud und den Nutzungsbedingungen für Google-APIs zuzustimmen.

    Wenn in Ihrem Skriptprojekt ein Standard-GCP-Projekt oder ein älteres Standard-GCP-Projekt verwendet wird, 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. Klicke 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 bestimmt

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.

Anfragen an Google-APIs können verschiedene Datentypen akzeptieren, darunter Pfadparameter, Abfrageparameter, einen Anfragetext und/oder einen Media-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.
  3. Der Anhang für den Media-Upload als Blob-Argument.
  4. Optionale Parameter 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).

Unterstützung für erweiterte Dienste

Erweiterte Dienste sind nur Thin Wrappers, die die Verwendung von Google-APIs in Apps Script ermöglichen. Daher ist jedes Problem, das bei der Verwendung auftritt, in der Regel ein Problem mit der zugrunde liegenden API und nicht mit Apps Script selbst.

Wenn Sie bei der Verwendung eines erweiterten Dienstes auf ein Problem stoßen, sollte es gemäß der Supportanleitung für die zugrunde liegende API gemeldet werden. Links zu diesen Supportanleitungen finden Sie in jedem Leitfaden für erweiterte Dienste im Abschnitt Referenz zu Apps Script.