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 dünne Wrapper um diese Google APIs. Sie funktionieren ähnlich wie die integrierten Dienste von Apps Script, sie bieten beispielsweise die automatische Vervollständigung und Apps Script führt die Autorisierung automatisch durch. 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 bei jeder anderen externen API eine Verbindung zu ihr herstellen.

Erweiterte Dienste oder HTTP?

Jeder der erweiterten Google-Dienste ist einer öffentlichen Google API zugeordnet. In Apps Script können Sie über erweiterte Dienste oder einfach direkt mit UrlFetch auf die APIs zugreifen.

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 für den direkten Zugriff auf die API verwenden, behandeln Sie die Google API im Grunde als externe API. Mit dieser Methode können alle Aspekte der API genutzt werden. Sie müssen die API-Autorisierung jedoch selbst durchführen. 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 zu verwenden, 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. Sie müssen in Ihrem Skriptprojekt den erweiterten Dienst aktivieren.

  2. Die API, die dem erweiterten Dienst entspricht, muss in dem 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 Sie dies noch nicht getan haben, werden Sie möglicherweise auch aufgefordert, den Nutzungsbedingungen von Google Cloud und 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 manuell im GCP-Projekt 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 dieser in der automatischen Vervollständigung verfügbar.

Methodensignaturen ermitteln

Erweiterte Dienste verwenden im Allgemeinen die gleichen 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 normalerweise 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 von verschiedenen Datentypen akzeptieren, einschließlich Pfadparametern, Abfrageparametern, eines Anfragetexts und/oder eines Anhangs für Medienuploads. Einige erweiterte Dienste können auch bestimmte HTTP-Anfrageheader akzeptieren (z. B. den erweiterten 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 Medienupload-Anhang als Blob-Argument.
  4. Optionale Parameter als Zuordnung von JavaScript-Objektnamen zu Werten.
  5. HTTP-Anfrageheader als JavaScript-Objekt, das Headerwerte den Headerwerten zuordnet.

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

Es gibt einige spezielle Ausnahmen:

  • Bei Methoden, die einen Medienupload akzeptieren, wird der Parameter uploadType automatisch festgelegt.
  • 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 JavaScript-Objekt für Anfrageheader festlegen, müssen Sie auch das optionale JavaScript-Objekt mit den Parametern festlegen (auf ein leeres Objekt, wenn Sie keine optionalen Parameter verwenden).

Support für erweiterte Dienste

Erweiterte Dienste sind nur dünne Wrapper, die die Verwendung einer Google API in Apps Script ermöglichen. Daher stellt jedes Problem, das bei der Verwendung auftritt, in der Regel ein Problem mit der zugrunde liegenden API dar, nicht mit Apps Script selbst.

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