Autorisierung für Editor-Add-ons

Die Autorisierung für viele Google Apps Script-Apps ist unkompliziert. Das Skriptprojekt fragt nach allen fehlenden Berechtigungen, 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 Mitbearbeiter freigegeben werden können. Mitbearbeiter, die das Editor-Add-on nicht installiert haben, sehen es in Dokumenten, in denen es vom Ersteller der Datei verwendet wurde.

• 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 Mitbearbeiter.

Status von Editor-Add-ons

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

• Ein Add-on ist für einen bestimmten Nutzer installiert , nachdem er oder sein Administrator es im Google Workspace Marketplace erworben und autorisiert hat, auf seine Google-Daten zuzugreifen.
• Ein Add-on ist in einem Dokument, Formular, einer Präsentation oder einer Tabelle aktiviert, wenn es dort von jemandem verwendet wird.
• Wenn mehrere Personen gemeinsam an einer Datei arbeiten und einer von ihnen ein Add-on verwendet, ist es für diesen Nutzer installiert und für die Datei aktiviert.

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

Autorisierungsmodi

Die Funktion onOpen eines Editor-Add-ons wird automatisch ausgeführt, wenn ein Nutzer ein Dokument, Formular, eine Präsentation oder eine Tabelle öffnet. Zum Schutz der Daten der Nutzer schränkt Apps Script ein, 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, im Formular, in der Präsentation oder in der Tabelle aktiviert ist, wird onOpen in AuthMode.LIMITED ausgeführt. Wenn das Add-on nicht aktiviert und nur installiert ist, onOpen in AuthMode.NONE ausgeführt wird.

In AuthMode.NONE kann ein Add-on bestimmte Dienste erst ausführen, wenn der Nutzer mit dem Add-on interagiert, indem er auf benutzerdefinierte Funktionen klickt oder diese ausführt. Wenn Ihr Add-on versucht, diese Dienste in onOpen, onInstall oder im globalen Bereich zu verwenden, schlagen Berechtigungen fehl und andere Aufrufe, z. B. das Ausfüllen von Menüs, werden beendet. „Hilfe“ ist die einzige unterstützte Option.

Um Aufrufe eingeschränkter Dienste auszuführen, müssen Sie den Autorisierungsmodus AuthMode.FULL verwenden. Funktionen für die Nutzerinteraktion, z. B. das Klicken auf eine Menüoption, werden nur in diesem Modus ausgeführt. Nachdem der Code im Modus AuthMode.FULL ausgeführt wurde, kann das Add-on alle autorisierten Bereiche verwenden.

Nur veröffentlichte Editor-Add-ons können sich in AuthMode.NONE befinden. Bei unveröffentlichten Editor-Add-ons wird onOpen in AuthMode.LIMITED ausgeführt. ist jedoch in beiden Autorisierungsmodi vorgesehen. Testen Sie dazu ein Editor-Add-on.

Apps Script übergibt den Autorisierungsmodus als das authMode Attribut des Apps Script Ereignisparameters, e. Der Wert von e.authMode entspricht einer Konstante in der Apps Script ScriptApp.AuthMode Enum.

Autorisierungsmodi gelten für alle Apps Script-Ausführungsmethoden, einschließlich der Ausführung über den Skripteditor, über ein Menüelement oder über einen Apps Script google.script.run-Aufruf. Das Attribut 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 ihren eigenen Autorisierungsmodus, AuthMode.CUSTOM_FUNCTION, der LIMITED ähnelt, aber etwas andere Einschränkungen hat. In allen anderen Fällen werden Skripts in AuthMode.FULL ausgeführt, wie in der folgenden Tabelle beschrieben.

Autorisierungslebenszyklus eines Editor-Add-ons

Wenn ein Add-on für den aktuellen Nutzer installiert oder in der aktuellen Datei aktiviert ist, wird es für das Dokument, Formular, die Präsentation oder die Tabelle geladen, wenn diese Datei geöffnet wird. 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 ein Menüelement unter Erweiterungen klickt, wird es ausgeführt.

Das Editor-Add-on ist installiert

Wenn ein Editor-Add-on aus dem Store installiert wird, wird die Funktion onInstall in AuthMode.FULL ausgeführt. In diesem Autorisierungsmodus kann das Add-on eine komplexe Einrichtungsroutine ausführen. Sie sollten onInstall auch verwenden, um Menüelemente zu erstellen, da das Dokument, Formular, die Präsentation oder die Tabelle bereits geöffnet ist und Ihre Funktion onOpen noch nicht ausgeführt wurde. Im folgenden Beispiel wird gezeigt, 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, und die Funktion onOpen wird für jedes Add-on 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 Funktion onOpen:

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 Attributen 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 Funktion onOpen, 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 weder die globalen Anweisungen noch onOpen ausgeführt werden. Wenn das veröffentlichte Add-on seine Menüelemente nicht hinzufügen kann, prüfen Sie in der Browserkonsole, ob ein Fehler zurückgegeben wurde. Prüfen Sie dann Ihr Skript, um festzustellen, ob die Funktion onOpen oder globale Variablen Dienste aufrufen, die in AuthMode.NONE nicht zulässig sind.

Add-ons können 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, führt das Skript die Funktion aus, die dem Menüelement in AuthMode.FULL entspricht. Das Add-on wird im Dokument, Formular, in der Präsentation oder in der Tabelle aktiviert, falls es noch nicht aktiviert war.

Fehlerbehebung bei nicht gerenderten Add-on-Menüs

Das Add-on-Menü wird möglicherweise nicht gerendert, wenn die Autorisierungsmodi in Ihrem Code nicht korrekt 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 ein Dienstaufruf in AuthMode.NONE Berechtigungsfehler verursacht, können Sie ihn entfernen oder neu anordnen. Gehen Sie dazu so vor:

1. Öffnen Sie das Apps Script-Projekt für Ihr Add-on und suchen Sie die Funktion onOpen.
2. Suchen Sie in der Funktion onOpen nach Erwähnungen von Apps Script-Diensten oder zugehörigen Objekten wie PropertiesService, SpreadsheetApp oder GmailApp.
3. 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 die folgenden Methoden übrig: .getUi, .createMenu, .addItem und .addToUi. Suchen und entfernen Sie auch alle Dienste, die sich außerhalb einer Funktion befinden.
4. 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 Ihre Codebasis neu an oder schreiben Sie sie um, um die in den vorherigen Schritten vorgenommenen Änderungen zu berücksichtigen.
5. 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 gesetzt ist und dass unter dem Feld „Konfiguration“ der Text Test in AuthMode.NONE angezeigt wird.
6. Starten Sie die Testbereitstellung und öffnen Sie das Menü Erweiterungen.
7. Wenn alle Menüelemente angezeigt werden, ist das Problem behoben. Wenn nur das Menü Hilfe angezeigt wird, kehren Sie zu Schritt 1 zurück. Möglicherweise haben Sie einen Dienstaufruf übersehen.

Weitere Informationen

• Webanwendungen
• Add-on-Typen
• Editor-Add-on testen