Autorisierung für Editor-Add-ons

Die Autorisierung für viele Google Apps Script-Apps ist unkompliziert. Das Scriptprojekt fordert alle fehlenden Berechtigungen an, die es benötigt, wenn jemand versucht, es zu verwenden.

Das Autorisierungsmodell für Editor-Add-ons ist aus mehreren Gründen komplexer:

Wenn ein Nutzer eine Datei erstellt, werden alle von ihm installierten Add-ons im Menü Erweiterungen aufgeführt, auch wenn er diese Add-ons noch nicht autorisiert hat.
Diese Add-ons funktionieren mit Dateien in Google Drive, die für Mitarbeiter freigegeben werden können. Mitbearbeiter, die das Editor-Add-on nicht installiert haben, sehen es in Dokumenten, in denen der Ersteller der Datei es verwendet hat.
Editor-Add-ons führen ihre onOpen-Funktionen automatisch aus, wenn ein Dokument geöffnet wird.

Zum Schutz von Nutzerdaten werden Autorisierungsmodi angewendet, die einige Dienste für onOpen nicht verfügbar machen. In diesem Leitfaden wird erläutert, was Ihr Code tun kann und wann.

Autorisierungsmodell

Der Autorisierungsmodus eines Editor-Add-ons hängt von seinem Status ab, der wiederum davon abhängt, wer es verwendet: der Nutzer, der das Add-on installiert hat, oder ein Mitarbeiter.

Status von Editor-Add-ons

Editor-Add-ons im Menü Erweiterungen sind installiert, aktiviert oder beides:

Ein Add-on wird für einen bestimmten Nutzer installiert, nachdem er oder sein Administrator es aus dem Google Workspace Marketplace bezogen und ihm den Zugriff auf seine Google-Daten autorisiert hat.
Ein Add-on ist in einem Dokument, Formular, einer Präsentation oder Tabelle aktiviert, wenn es dort von jemandem verwendet wird.
Wenn mehrere Personen an einer Datei zusammenarbeiten und eine von ihnen ein Add‑on verwendet, wird es für diese Person installiert und für die Datei aktiviert.

In der folgenden Tabelle werden die Unterschiede zwischen „installiert“ und „aktiviert“ zusammengefasst. Wenn Sie ein Script als Add-on testen, können Sie den Test in einem oder beiden Zuständen ausführen.

	Installiert	Aktiviert
Gilt für	Nutzer	Dokument, Formular, Präsentation oder Tabelle
Ursache:	Add‑on aus dem Store beziehen	Sie rufen ein Add-on aus dem Store auf, während Sie das Dokument, Formular, die Präsentation oder die Tabelle verwenden, oder Sie verwenden ein zuvor installiertes Add-on in diesem Dokument, Formular, dieser Präsentation oder Tabelle.
Menü sichtbar für	Nur dieser Nutzer in allen Dokumenten, Formularen, Präsentationen oder Tabellen, die er öffnet oder erstellt	Alle Mitbearbeiter dieses Dokuments, Formulars, dieser Präsentation oder Tabelle
Autorisierungsmodus für `onOpen`	`AuthMode.NONE` (es sei denn, sie ist auch aktiviert, in diesem Fall `AuthMode.LIMITED)`	`AuthMode.LIMITED`

Autorisierungsmodi

Die onOpen-Funktion eines Editor-Add-ons wird automatisch ausgeführt, wenn ein Nutzer ein Dokument, ein Formular, eine Präsentation oder eine Tabelle öffnet. Zum Schutz der Nutzerdaten wird durch Apps Script eingeschränkt, was die Funktion onOpen tun kann. Der Status des Editor-Add-ons bestimmt, in welchem Autorisierungsmodus die Funktion onOpen ausgeführt wird.

Wenn ein Editor-Add-on in der Datei, dem Formular, der Präsentation oder der Tabelle aktiviert ist, wird onOpen in AuthMode.LIMITED ausgeführt. Wenn das Add-on nicht aktiviert, sondern nur installiert ist, wird onOpen in AuthMode.NONE ausgeführt.

In AuthMode.NONE können bestimmte Dienste erst ausgeführt werden, wenn der Nutzer durch Klicken oder Ausführen benutzerdefinierter Funktionen mit dem Add‑on interagiert. Wenn Ihr Add-on versucht, diese Dienste im Bereich onOpen, onInstall oder im globalen Bereich zu verwenden, schlagen Berechtigungen fehl und andere Aufrufe, z. B. zum Ausfüllen von Menüs, werden beendet. „Hilfe“ ist die einzige unterstützte Option.

Wenn Sie eingeschränkte Dienstaufrufe ausführen möchten, müssen Sie den Autorisierungsmodus AuthMode.FULL verwenden. Funktionen für Nutzerinteraktionen, z. B. das Klicken auf eine Menüoption, werden nur in diesem Modus ausgeführt. Nachdem der Code im AuthMode.FULL-Modus ausgeführt wurde, kann das Add-on alle autorisierten Bereiche verwenden.

Nur veröffentlichte Editor-Add-ons können in AuthMode.NONE verwendet werden. Nicht veröffentlichte Editor-Add-ons werden onOpen in AuthMode.LIMITED ausgeführt. ist jedoch in beiden Autorisierungsmodi vorgesehen. Dazu müssen Sie ein Editor-Add-on testen.

Apps Script übergibt den Autorisierungsmodus als authMode-Property des Apps Script-Ereignisparameters, e. Der Wert von e.authMode entspricht einer Konstanten im Apps Script-Enum ScriptApp.AuthMode.

Autorisierungsmodi gelten für alle Apps Script-Ausführungsmethoden, einschließlich der Ausführung über den Script-Editor, über ein Menüelement oder über einen Apps Script-google.script.run-Aufruf. Die Property e.authMode kann jedoch nur geprüft werden, wenn das Skript als Ergebnis eines Triggers wie onOpen, onEdit oder onInstall ausgeführt wird. Benutzerdefinierte Funktionen in Google Sheets verwenden einen eigenen Autorisierungsmodus, AuthMode.CUSTOM_FUNCTION, der LIMITED ähnelt, aber leicht unterschiedliche Einschränkungen hat. In allen anderen Fällen werden Skripts in AuthMode.FULL ausgeführt, wie in der folgenden Tabelle beschrieben.

	`NONE`	`LIMITED`	`CUSTOM_FUNCTION`	`FULL`
Tritt auf für	`onOpen` (wenn der Nutzer ein Add-on installiert, es aber nicht im Dokument, Formular, in der Präsentation oder Tabelle aktiviert hat)	`onOpen` (zu allen anderen Zeiten) `onEdit` (nur in Google Sheets)	Benutzerdefinierte Funktionen	Zu allen anderen Zeiten, einschließlich: Installierbare Trigger `onInstall` `google.script.run`
Zugriff auf Nutzerdaten	Nur Gebietsschema	Nur Gebietsschema	Nur Gebietsschema	Ja
Zugriff auf Dokumente, Formulare, Präsentationen oder Tabellen	Nein	Ja	Ja – schreibgeschützt	Ja
Zugriff auf die Benutzeroberfläche	Menüelemente hinzufügen	Menüelemente hinzufügen	Nein	Ja
Zugriff auf `Properties`	Nein	Ja	Ja	Ja
Zugriff auf `Jdbc`, `UrlFetch`	Nein	Nein	Ja	Ja
Weitere Dienste	`Logger` `Utilities`	Dienste, die nicht auf Nutzerdaten zugreifen	Dienste, die nicht auf Nutzerdaten zugreifen	Alle Dienste

Autorisierungslebenszyklus eines Editor-Add-ons

Wenn ein Add-on für den aktuellen Nutzer installiert oder in der aktuellen Datei aktiviert ist, wird es beim Öffnen der Datei für das Dokument, Formular, die Präsentation oder die Tabelle geladen. Das Add-on wird im Menü Erweiterungen aufgeführt und beginnt, auf die einfachen Trigger onInstall, onOpen und onEdit zu warten. Wenn ein Nutzer auf das Menüelement Erweiterungen klickt, wird es ausgeführt.

Das Editor-Add-on ist installiert.

Wenn ein Editor-Add‑on aus dem Store installiert wird, wird seine onInstall-Funktion in AuthMode.FULL ausgeführt. In diesem Autorisierungsmodus kann das Add-on eine komplexe Einrichtungsroutine ausführen. Sie sollten auch onInstall verwenden, um Menüelemente zu erstellen, da das Dokument, Formular, die Präsentation oder die Tabelle bereits geöffnet ist und Ihre onOpen-Funktion noch nicht ausgeführt wurde. Das folgende Beispiel zeigt, wie die Funktion onOpen aus der Funktion onInstall aufgerufen wird:

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

Das Editor-Add-on wird geöffnet.

Wenn ein Dokument, Formular, eine Präsentation oder eine Tabelle geöffnet wird, werden alle Editor-Add-ons geladen, die der aktuelle Nutzer installiert hat oder die ein Mitbearbeiter in der Datei aktiviert hat. Anschließend wird die onOpen-Funktion jedes Add-ons aufgerufen. Der Autorisierungsmodus, in dem onOpen ausgeführt wird, hängt davon ab, ob ein Add‑on installiert oder aktiviert ist.

Wenn ein Add-on nur ein einfaches Menü erstellt, spielt der Modus keine Rolle. Das folgende Beispiel zeigt eine einfache onOpen-Funktion:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

Wenn Sie dynamische Menüelemente basierend auf gespeicherten Apps Script-Eigenschaften hinzufügen, den Inhalt der aktuellen Datei lesen oder andere erweiterte Aufgaben ausführen möchten, müssen Sie den Autorisierungsmodus identifizieren und entsprechend verarbeiten.

Das folgende Beispiel zeigt eine erweiterte onOpen-Funktion, die ihre Aktion basierend auf dem Autorisierungsmodus ändert:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

Wenn die Funktion onOpen ausgeführt wird, wird das gesamte Skript geladen und globale Anweisungen werden im selben Autorisierungsmodus wie onOpen ausgeführt. Wenn der Autorisierungsmodus die globalen Anweisungen verbietet, können sowohl die globalen Anweisungen als auch onOpen nicht ausgeführt werden. Wenn das veröffentlichte Add-on seine Menüelemente nicht hinzufügt, sehen Sie in der Browserkonsole nach, ob ein Fehler zurückgegeben wurde. Prüfen Sie dann Ihr Script, um festzustellen, ob die Funktion onOpen oder globale Variablen Dienste aufrufen, die in AuthMode.NONE nicht zulässig sind.

Add-ons können beim Ausführen in AuthMode.LIMITED keine Seitenleisten oder Dialogfelder öffnen. Sie können Menüelemente verwenden, um Seitenleisten und Dialogfelder zu öffnen, da diese in AuthMode.FULL ausgeführt werden.

Ein Nutzer führt das Editor-Add-on aus.

Wenn ein Nutzer auf ein Menüelement unter Erweiterungen klickt, prüft Apps Script zuerst, ob der Nutzer das Add-on installiert hat, und fordert ihn gegebenenfalls dazu auf. Wenn der Nutzer das Add-on autorisiert hat, wird die Funktion, die dem Menüpunkt in AuthMode.FULL entspricht, vom Script ausgeführt. Das Add-on wird im Dokument, Formular, in der Präsentation oder Tabelle aktiviert, sofern es nicht bereits aktiviert war.

Fehlerbehebung bei Add‑on-Menüs, die nicht gerendert werden

Das Add-on-Menü wird möglicherweise nicht gerendert, wenn in Ihrem Code die Autorisierungsmodi nicht richtig verwaltet werden. Beispiel:

Ein Add-on versucht, einen Apps Script-Dienst auszuführen, der vom aktuellen Autorisierungsmodus nicht unterstützt wird.
Ein Add-on versucht, einen Dienstaufruf auszuführen, bevor ein Nutzer damit interagiert.

Wenn Sie einen Dienstaufruf entfernen oder neu anordnen möchten, der Berechtigungsfehler in AuthMode.NONE verursacht, versuchen Sie Folgendes:

Öffnen Sie das Apps Script-Projekt für Ihr Add-on und suchen Sie die Funktion onOpen.
Suchen Sie in der Funktion onOpen nach Erwähnungen von Apps Script-Diensten oder zugehörigen Objekten wie PropertiesService, SpreadsheetApp oder GmailApp.
Wenn ein Dienst für etwas anderes als das Erstellen der UI-Elemente verwendet wird, entfernen Sie ihn oder schließen Sie ihn in einen Kommentarblock ein. Lassen Sie nur diese Methoden übrig: .getUi, .createMenu, .addItem und .addToUi. Suchen Sie auch nach Diensten, die nicht zu einer Funktion gehören, und entfernen Sie sie.
Identifizieren Sie Funktionen, die die im vorherigen Schritt auskommentierten oder entfernten Codezeilen enthalten könnten, insbesondere solche, die die von ihnen erzeugten Informationen verwenden, und verschieben Sie die Dienstaufrufe in die Funktionen, die sie benötigen. Ordnen Sie Ihren Code neu an oder schreiben Sie ihn um, um die Änderungen aus den vorherigen Schritten zu berücksichtigen.
Speichern Sie den Code und erstellen Sie eine Testbereitstellung. Achten Sie beim Erstellen einer Testbereitstellung darauf, dass das Feld Konfiguration auf Für aktuellen Nutzer installiert festgelegt ist und dass unter dem Feld „Konfiguration“ der Text In AuthMode.NONE testen angezeigt wird.
Starten Sie die Testbereitstellung und öffnen Sie das Menü Erweiterungen.
Wenn alle Menüelemente angezeigt werden, ist das Problem behoben. Wenn Sie nur das Menü Hilfe sehen, kehren Sie zu Schritt 1 zurück. Möglicherweise haben Sie einen Anruf vom Kundenservice verpasst.

Autorisierung für Editor-Add-ons Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.