Autorisierung für Editor-Add-on

Die Autorisierung ist bei vielen Apps Script-basierten Apps unkompliziert, Skriptprojekt fragt nach fehlenden Berechtigungen, wenn jemand versucht, um sie zu verwenden.

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

• Wenn ein Nutzer eine Datei erstellt, werden alle installierten Add-ons im Menü Erweiterungen aufgeführt, auch wenn der Nutzer 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 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 der Nutzerdaten werden Autorisierungsmodi angewendet, durch die einige Dienste nicht verfügbar für onOpen(). In diesem Leitfaden erfahren Sie, was Sie tun können und wann.

Autorisierungsmodell

Der Autorisierungsmodus eines Editor-Add-ons hängt davon ab, Status, der davon abhängt, wer es verwendet: dem Nutzer, der das Add-on installiert hat oder Mitbearbeiter.

Status des 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 im Google Workspace Marketplace heruntergeladen und autorisiert hat, auf seine Google-Daten zuzugreifen.
• Add-ons werden in einem Dokument, Formular, Präsentation oder Tabellenkalkulation, wenn jemand sie dort benutzt.
• Wenn Personen gemeinsam an einer Datei arbeiten und einer von ihnen ein wird es für den einen Nutzer installiert und enabled.

In der folgenden Tabelle werden die Unterschiede zwischen installiert und aktiviert zusammengefasst. Wenn Sie Script 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 ausgeführt automatisch, wenn ein Nutzer ein Dokument, ein Formular, eine Präsentation oder eine Tabelle öffnet. Zum Schutz der Daten der Nutzer werden die Funktionen der onOpen()-Funktion in Apps Script eingeschränkt. Der Status des Editor-Add-ons bestimmt, in welchem Autorisierungsmodus die onOpen()-Funktion 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 ist und nur installiert ist, onOpen() wird in AuthMode.NONE ausgeführt.

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

Zum Ausführen eingeschränkter Dienstaufrufe müssen Sie die AuthMode.FULL-Autorisierung verwenden . Funktionen für Nutzerinteraktionen, z. B. das Klicken auf eine Menüoption, nur in diesem Modus ausgeführt werden. Nachdem der Code im AuthMode.FULL-Modus ausgeführt wurde, wird der kann das Add-on alle vom Nutzer autorisierten Bereiche verwenden.

In Apps Script wird der Autorisierungsmodus als authMode-Eigenschaft des Apps Script-Ereignisparameters e übergeben. Der Wert von e.authMode entspricht einer Konstante im Apps Script-Enum ScriptApp.AuthMode.

Autorisierungsmodi gelten für alle Ausführungsmethoden von Apps Script, einschließlich der Ausführung über den Script-Editor, über einen Menüpunkt oder über einen Apps Script-Aufruf google.script.run. Die Property e.authMode kann jedoch nur geprüft werden, wenn das Script als Ergebnis eines Triggers wie onOpen(), onEdit() oder onInstall() ausgeführt wird. Für benutzerdefinierte Funktionen in Google Tabellen wird ein eigener Autorisierungsmodus verwendet, AuthMode.CUSTOM_FUNCTION. Dieser ähnelt LIMITED, hat aber leicht abweichende Einschränkungen. Für alle In anderen Fällen werden Skripts in AuthMode.FULL ausgeführt, wie im Folgenden beschrieben .

Autorisierungszyklus eines Editor-Add-ons

Wenn ein Add-on für den aktuellen Nutzer installiert wird oder in der aktuellen Datei aktiviert ist, das Add-on für das Dokument, das Formular, die Präsentation oder eine Tabellenkalkulation beim Öffnen der Datei. 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 einen Menüpunkt Erweiterungen klickt, wird er ausgeführt.

Das Editor-Add-on ist installiert

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

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

Das Editor-Add-on ist geöffnet

Wenn ein Dokument, ein Formular, eine Präsentation oder eine Tabelle geöffnet wird, Editor-Add-on, das der aktuelle Nutzer installiert hat, oder die jeder Mitbearbeiter in der Datei aktiviert hat, und ruft jeder ihrer onOpen()-Funktionen. Der Autorisierungsmodus, der onOpen() hängt davon ab, ob ein Add-on installiert oder aktiviert ist.

Wenn mit einem Add-on nur ein einfaches Menü erstellt wird, wird der Modus ist egal. 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();
}

So fügen Sie dynamische Menüpunkte basierend auf gespeichertem Apps Script hinzu: properties, mit dem Sie den Inhalt der Property lesen können. oder andere erweiterte Aufgaben ausführen, muss den Autorisierungsmodus identifizieren und entsprechend behandeln.

Das folgende Beispiel zeigt eine erweiterte onOpen()-Funktion, die ihre Aktion basierend auf dem Autorisierungsmodus ausführen:

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();
}

Beachten Sie, dass Add-ons bei der Ausführung in AuthMode.LIMITED Sie können die Menüpunkte 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 den Menüpunkt Erweiterungen klickt, wird zuerst geprüft, ob er das Add-on installiert hat. Andernfalls wird er aufgefordert, dies zu tun. Wenn der Nutzer die Add-on führt das Skript die Funktion aus, entspricht dem Menüpunkt in AuthMode.FULL. Das Add-on ist im Dokument, Formular, in der Präsentation oder in der Tabelle aktiviert, falls nicht bereits geschehen.

Fehlerbehebung bei nicht gerenderten Add-on-Menüs

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

• Ein Add-on versucht, ein Apps Script auszuführen der vom aktuellen Autorisierungsmodus nicht unterstützt wird.

• Ein Add-on versucht, einen Dienstaufruf auszuführen, bevor ein Nutzer damit interagieren.

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

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. Wird ein Dienst für etwas anderes als das Erstellen der UI-Elemente verwendet, entfernen oder in einen Kommentarblock umschließen. Lassen Sie nur die folgenden Methoden: .getUi(), .createMenu(), .addItem() und .addToUi(). Suchen und entfernen Sie auch alle Dienste, die sich außerhalb einer Funktion befinden.
4. Identifizieren von Funktionen, die Codezeilen enthalten könnten, die kommentiert oder entfernt wurden vor allem für diejenigen, die die gewonnenen Informationen nutzen, und verschieben Sie die Dienstaufrufe in die Funktionen, die sie benötigen. Neu anordnen oder umschreiben Ihre Codebasis, 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 im Feld Konfiguration Für den aktuellen Nutzer installiert steht und dass unter dem Feld „Konfiguration“ der Text In AuthMode.None testen zu sehen ist.

6. Starten Sie die Testbereitstellung und öffnen Sie das Menü Erweiterungen.

7. Wenn alle Menüpunkte angezeigt werden, ist das Problem behoben. Wenn nur das Menü Hilfe angezeigt wird, fahre mit Schritt 1 fort. Möglicherweise haben Sie einen Serviceanruf verpasst.

Weitere Informationen

• Web-Apps
• Add-on-Typen
• Editor-Add-on testen