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 bei einem Zugriff auf die App nach fehlenden Berechtigungen fragt.

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.
Die onOpen()-Funktionen von Editor-Add-ons werden automatisch ausgeführt, wenn ein Dokument geöffnet wird.

Zum Schutz von Nutzerdaten werden Autorisierungsmodi angewendet, die einige Dienste für onOpen() unzugänglich machen. In diesem Leitfaden erfahren Sie, 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 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.
Ein Add-on ist in einem Dokument, Formular, einer Präsentation oder Tabelle aktiviert, wenn es dort von einem Nutzer verwendet wird.
Wenn mehrere Nutzer gemeinsam an einer Datei arbeiten und einer von ihnen ein Add-on verwendet, wird es für diesen Nutzer 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 dieser Status ausführen.

	Installiert	Aktiviert
Gilt für	Nutzer	Dokument, Formular, Präsentation oder Tabelle
Ursache:	Add-on im Store kaufen	Sie können ein Add-on aus dem Store herunterladen, während Sie das Dokument, Formular, die Präsentation oder die Tabelle verwenden, oder ein zuvor installiertes Add-on in diesem Dokument, Formular, dieser Präsentation oder dieser Tabelle verwenden.
Menü sichtbar für	Nur für diesen Nutzer in allen Dokumenten, Formularen, Präsentationen oder Tabellen, die er öffnet oder erstellt	Alle Mitbearbeiter an diesem Dokument, Formular, dieser Präsentation oder dieser Tabelle
Autorisierungsmodus für `onOpen()`	`AuthMode.NONE` sofern sie nicht auch aktiviert ist, 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 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, sondern nur installiert ist, wird onOpen() 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 Add-on versucht, diese Dienste im onOpen()-, onInstall()- oder globalen Umfang zu verwenden, schlagen die Berechtigungen fehl und andere Aufrufe, z. B. das Ausfüllen von Menüs, werden beendet. Die 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 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. In allen anderen Fällen werden Scripts 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 in der Tabelle aktiviert hat)	`onOpen()` (alle anderen Zeiten) `onEdit()` (nur in Google Tabellen)	Benutzerdefinierte Funktionen	In allen anderen Fällen, einschließlich: installierbare Trigger `onInstall()` `google.script.run`
Zugriff auf Nutzerdaten	Nur Sprache	Nur Sprache	Nur Sprache	Ja
Zugriff auf ein Dokument, Formular, eine Präsentation oder eine Tabelle	Nein	Ja	Ja – schreibgeschützt	Ja
Zugriff auf die Benutzeroberfläche	Menüpunkte hinzufügen	Menüpunkte 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

Autorisierungszyklus 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 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 kann das Add-on einen komplexen Einrichtungsablauf 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. Im folgenden Beispiel wird gezeigt, wie die Funktion onOpen() über die Funktion onInstall() aufgerufen wird:

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

Das Editor-Add-on wird geöffnet.

Wenn ein Dokument, ein Formular, eine Präsentation oder eine Tabelle geöffnet wird, werden alle Editor-Add-ons geladen, die der aktuelle Nutzer installiert hat oder die Mitbearbeiter in der Datei aktiviert haben. Außerdem werden alle zugehörigen onOpen()-Funktionen 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üpunkte basierend auf gespeicherten Apps Script-Properties hinzufügen, den Inhalt der aktuellen Datei lesen oder andere erweiterte Aufgaben ausführen möchten, müssen Sie den Autorisierungsmodus angeben und entsprechend verarbeiten.

Das folgende Beispiel zeigt eine erweiterte onOpen()-Funktion, die ihre Aktion je nach 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ü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 das Add-on autorisiert hat, führt das Script die Funktion aus, die dem Menüpunkt in AuthMode.FULL entspricht. 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, 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 nach der 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 nicht nur zum Erstellen der UI-Elemente verwendet wird, entfernen Sie ihn oder setzen Sie ihn in einen Kommentarblock. Lassen Sie nur die folgenden Methoden: .getUi(), .createMenu(), .addItem() und .addToUi(). Suchen und entfernen Sie auch alle Dienste, die nicht zu einer Funktion gehören.
Suchen Sie nach Funktionen, die die im vorherigen Schritt kommentierten oder entfernten Codezeilen enthalten könnten, insbesondere nach solchen, die die von ihnen generierten Informationen verwenden, und verschieben Sie die Dienstaufrufe in die Funktionen, in denen sie benötigt werden. Ordnen Sie die Codebasis neu an oder schreiben Sie sie um, um die in den vorherigen Schritten vorgenommenen Änderungen zu berücksichtigen.
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.
Starten Sie die Testbereitstellung und öffnen Sie das Menü Erweiterungen.
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.