Diese Seite wurde von der Cloud Translation API übersetzt.

Autorisierung für Editor-Add-ons

Die Autorisierung für viele Apps Script-basierte Apps ist unkompliziert, da das Script-Projekt alle fehlenden Berechtigungen anfordert, 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 Add-on „Editor“ 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 erfahren Sie, was Ihr Code leisten 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 heruntergeladen und 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 Skript als Add-on testen, können Sie den Test in einem oder beiden dieser Zustände 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 dem Dokument, Formular, der Präsentation oder der 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 Funktion onOpen() 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 schränkt Apps Script die Möglichkeiten der Funktion onOpen() ein. 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 Bereiche verwenden, die der Nutzer autorisiert hat.

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 mit dem Abhören der einfachen Trigger onInstall(), onOpen() und onEdit(). 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 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();
}

Hinweis: 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 das Add-on installiert ist, und fordert den Nutzer gegebenenfalls dazu auf. Wenn der Nutzer das Add-on autorisiert hat, wird die Funktion ausgeführt, die dem Menüpunkt in AuthMode.FULL entspricht. 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 die folgenden Methoden übrig: .getUi(), .createMenu(), .addItem() und .addToUi(). Suchen Sie auch nach Diensten, die sich außerhalb einer Funktion befinden, 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üpunkte 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.