Bibliotheken

Eine Bibliothek ist ein Skriptprojekt, dessen Funktionen in anderen Skripts wiederverwendet werden können.

Ein Skript, das eine Bibliothek verwendet wird nicht so schnell ausgeführt als wenn der gesamte Code in einem einzigen Skriptprojekt enthalten wäre. Bibliotheken können die Entwicklung und Wartung zwar erleichtern, sollten aber in Projekten, in denen Geschwindigkeit entscheidend ist, nur sparsam eingesetzt werden. Aus diesem Grund sollte die Verwendung von Bibliotheken in Google Workspace-Add-ons eingeschränkt werden.

Zugriff auf eine Bibliothek erhalten

Wenn Sie eine Bibliothek in Ihr Projekt einbinden möchten, benötigen Sie mindestens Zugriff auf Ansichtsebene. Wenn Sie nicht der Autor der Bibliothek sind, die Sie einbinden möchten, wenden Sie sich an den Autor und fordern Sie Zugriff an.

Sie benötigen die Skript-ID der Bibliothek, die Sie einbinden möchten. Wenn Sie Zugriff auf die Bibliothek haben, finden Sie die Skript-ID auf der Seite Projekteinstellungen .

Bibliothek zu Ihrem Skriptprojekt hinzufügen

Klicken Sie links im Apps Script-Editor neben „Bibliotheken“ auf „Bibliothek hinzufügen“ .
Fügen Sie im Feld „Skript-ID“ die Skript-ID der Bibliothek ein.
Klicken Sie auf Suchen.
Wenn ein Fehler auftritt, prüfen Sie, ob Sie mindestens Zugriff auf Ansichtsebene für das Projekt haben, das Sie einbinden möchten.
Klicken Sie auf das Drop-down-Menü Version und wählen Sie die Version der Bibliothek aus, die Sie verwenden möchten.
Prüfen Sie, ob der Standardname „ID“ der Name ist, den Sie für diese Bibliothek verwenden möchten. Dieser Name wird von Ihrem Skript verwendet, um auf die Bibliothek zu verweisen. Wenn Sie ihn beispielsweise auf Test setzen, rufen Sie eine Methode dieser Bibliothek so auf: Test.libraryMethod.
Wenn Sie einen ID-Namen verwenden, der mit dem Namen eines bereits vorhandenen Dienstes wie MailApp oder einer zuvor hinzugefügten Bibliothek übereinstimmt, überschreibt die zuletzt hinzugefügte Bibliothek den vorhandenen Dienst oder die vorhandene Bibliothek.
Klicken Sie auf Hinzufügen.

Bibliothek verwenden

Verwenden Sie die eingebundene Bibliothek wie einen Standarddienst. Wenn Test beispielsweise die ID für Ihre Bibliothek ist, geben Sie Test ein und setzen Sie direkt danach einen Punkt, um die Liste der Methoden in der Bibliothek aufzurufen.

So öffnen Sie die Referenzdokumentation für eine eingebundene Bibliothek:

Klicken Sie links im Skripteditor neben dem Bibliotheksnamen auf das Dreipunkt-Menü > In neuem Tab öffnen.

Bibliothek entfernen

Klicken Sie links im Skripteditor neben dem Bibliotheksnamen auf das Dreipunkt-Menü > Entfernen > Bibliothek entfernen.

Wenn eine Bibliothek vom Autor gelöscht wird, müssen Sie sie trotzdem aus der Liste der eingebundenen Bibliotheken entfernen.

Bibliothek aktualisieren

Ändern Sie die Version der Bibliothek oder aktualisieren Sie ihre ID.

Klicken Sie links im Editor unter „Bibliotheken“ auf den Namen der Bibliothek.
Nehmen Sie die Änderungen vor und klicken Sie auf Speichern.

Bibliothek erstellen und freigeben

So verwenden und teilen Sie Ihr Skriptprojekt als Bibliothek:

Erstellen Sie eine versionierte Bereitstellung Ihres Skripts.
Geben Sie allen potenziellen Nutzern der Bibliothek mindestens Zugriff auf Ansichtsebene.
Geben Sie diesen Nutzern die Skript-ID, die Sie auf der Project Settings Seite finden.

Best Practices

Hier sind einige Richtlinien, die Sie beim Schreiben einer Bibliothek beachten sollten:

Wählen Sie einen aussagekräftigen Namen für Ihr Projekt aus, da dieser als Standard-ID verwendet wird, wenn Ihre Bibliothek von anderen eingebunden wird.
Wenn Sie eine oder mehrere Methoden Ihres Skripts für Ihre Bibliotheksnutzer nicht sichtbar (und nicht nutzbar) machen möchten, beenden Sie den Namen der Methode mit einem Unterstrich. Beispiel: myPrivateMethod_.
Für Bibliotheksnutzer sind nur aufzählbare globale Properties sichtbar. Dazu gehören Funktionsdeklarationen, Variablen, die außerhalb einer Funktion mit var erstellt wurden, und Properties, die explizit für das globale Objekt festgelegt wurden. Mit Object.defineProperty() und enumerable auf false wird beispielsweise ein Symbol erstellt, das Sie in Ihrer Bibliothek verwenden können. Auf dieses Symbol können Ihre Nutzer jedoch nicht zugreifen.

Damit Ihre Bibliotheksnutzer die automatische Vervollständigung des Skripteditors und die automatisch generierte Dokumentation nutzen können, fügen Sie für alle Ihre Funktionen eine Dokumentation im JSDoc-Stil ein. Hier ein Beispiel:

/**
 * Raises a number to the given power, and returns the result.
 *
 * @param {number} base the number we're raising to a power
 * @param {number} exp the exponent we're raising the base to
 * @return {number} the result of the exponential calculation
 */
function power(base, exp) { ... }

Ressourcenbereich

Bei der Arbeit mit Bibliotheken gibt es zwei Arten von Ressourcen: freigegebene und nicht freigegebene. Eine freigegebene Ressource bedeutet, dass sowohl die Bibliothek als auch das einbindende Skript einen integrierten Zugriff auf dieselbe Instanz der Ressource haben. Das folgende Diagramm veranschaulicht eine freigegebene Ressource am Beispiel von Nutzereigenschaften:

Freigegebene Ressource

Eine nicht freigegebene Ressource bedeutet, dass sowohl die Bibliothek als auch das einbindende Skript nur einen integrierten Zugriff auf ihre eigene Instanz der Ressource haben. Eine Bibliothek kann jedoch Zugriff auf ihre nicht freigegebenen Ressourcen gewähren, indem sie explizite Funktionen enthält, die auf diese Ressourcen angewendet werden. Hier ist ein Beispiel für eine Funktion, die Sie in Ihre Bibliothek einbinden können, um ihre Skripteigenschaften verfügbar zu machen:

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

Das folgende Diagramm veranschaulicht eine nicht freigegebene Ressource am Beispiel von Skripteigenschaften:

Beispiel für eine nicht freigegebene Ressource

In dieser Tabelle sind die freigegebenen und nicht freigegebenen Ressourcen aufgeführt:

Ressource	Freigegeben*	Nicht freigegeben**	Hinweise
Sperren			Dieselbe Instanz ist für alle einbindenden Skripts sichtbar, wenn sie in der Bibliothek erstellt wurde.
Skripteigenschaften			Dieselbe Instanz ist für alle einbindenden Skripts sichtbar, wenn sie in der Bibliothek erstellt wurde.
Cache			Dieselbe Instanz ist für alle einbindenden Skripts sichtbar, wenn sie in der Bibliothek erstellt wurde.
Trigger			Einfache Trigger, die in der Bibliothek erstellt wurden, werden nicht vom einbindenden Skript ausgelöst.
ScriptApp
UiApp
Nutzereigenschaften
Logger und Ausführungsprotokoll
Sites, Tabellen und andere Container			Ein Aufruf von `getActive` gibt den Container des einbindenden Skripts zurück.
MailApp und GmailApp
* Das bedeutet, dass die Bibliothek keine eigene Instanz der Funktion/Ressource hat, sondern die Instanz verwendet, die vom Skript erstellt wurde, das sie aufgerufen hat. ** Das bedeutet, dass die Bibliothek eine eigene Instanz der Ressource/Funktion hat und dass alle Skripts, die die Bibliothek verwenden, diese Instanz gemeinsam nutzen und Zugriff darauf haben.

Bibliothek testen

Verwenden Sie die Head-Bereitstellung, um Ihre Bibliothek zu testen. Jeder, der Zugriff auf Editorebene für das Skript hat, kann die Head-Bereitstellung verwenden.

Es muss mindestens eine Version der Bibliothek gespeichert sein.

Fehler in einer Bibliothek beheben

Wenn Sie ein Skript debuggen, das eine Bibliothek enthält, können Sie nicht in den Bibliothekscode eintreten oder Breakpoints darin setzen. Wenn Sie im Debugmodus versuchen, in eine Bibliotheksfunktion einzutreten, überspringt der Debugger die Funktion und geht zur nächsten Zeile im aufrufenden Skript.

Wenn Sie HEAD (Entwicklungsmodus) für die Bibliotheksversion verwenden, können Sie nicht in die Bibliothek eintreten oder Breakpoints darin setzen.

Verwenden Sie eine der folgenden Methoden, um Fehler im Bibliothekscode zu beheben:

Aus dem Bibliotheksprojekt debuggen: Öffnen Sie das Bibliotheksskriptprojekt im Apps Script-Editor. Wenn Sie Bibliotheksfunktionen mit bestimmten Argumenten testen möchten, erstellen Sie im Bibliotheksprojekt eine temporäre Testfunktion, die Ihre Bibliotheksfunktionen aufruft, und führen Sie diese Testfunktion dann im Debugmodus aus.
Logging: Verwenden Sie console.log() in Ihren Bibliotheksfunktionen, um Informationen in die Ausführungsprotokolle auszugeben. Wenn die Bibliothek von einem anderen Skript aufgerufen wird, werden diese Protokolle in den Ausführungsprotokollen des aufrufenden Skripts angezeigt.