Diese Seite wurde von der Cloud Translation API übersetzt.

Autorisierung für Add-ons für Bearbeiter

Die Autorisierung für viele Apps Script-basierte Anwendungen ist unkompliziert, da das Skriptprojekt nach fehlenden Berechtigungen fragt, die benötigt werden, 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, selbst wenn der Nutzer diese Add-ons noch nicht autorisiert hat.
Diese Add-ons funktionieren an 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 Dateiersteller 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, durch die einige Dienste für onOpen() nicht mehr verfügbar sind. In diesem Leitfaden erfährst du, was du mit deinem Code machen kannst und wann.

Autorisierungsmodell

Der Autorisierungsmodus eines Editor-Add-ons hängt von seinem Status ab, der davon abhängt, wer es verwendet: den 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 aus dem Google Workspace Marketplace abgerufen und für den Zugriff auf seine Google-Daten autorisiert hat.
Ein Add-on wird in einem Dokument, einem Formular, einer Präsentation oder einer Tabelle aktiviert, wenn es dort verwendet wird.
Wenn Personen gemeinsam an einer Datei arbeiten und einer von ihnen ein Add-on verwendet, wird es für den einen 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 dieser Status ausführen.

	Installiert	Aktiviert
Gilt für:	Nutzer	Dokument, Formular, Präsentation oder Tabelle
Ursache:	Add-on aus dem Store herunterladen	Ein Add-on aus dem Store herunterladen, während das Dokument, das Formular, die Präsentation oder die Tabelle verwendet wird, oder ein zuvor installiertes Add-on in einem Dokument, Formular, einer Präsentation oder einer Tabelle verwenden
Menü sichtbar für	Nur dieser Nutzer in allen Dokumenten, Formularen, Präsentationen oder Tabellen, die er öffnet oder erstellt	Alle Mitbearbeiter des Dokuments, des Formulars, der Präsentation oder der Tabelle
Autorisierungsmodus für `onOpen()`	`AuthMode.NONE` (es sei denn, es 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 Funktionen 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 und nur installiert ist, wird onOpen() in AuthMode.NONE ausgeführt.

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

Wenn Sie eingeschränkte Dienstaufrufe ausführen möchten, müssen Sie den Autorisierungsmodus AuthMode.FULL verwenden. Nutzerinteraktionsfunktionen wie 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.

Apps Script übergibt den Autorisierungsmodus als 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 google.script.run-Aufruf von Apps Script. 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 Tabellen verwenden den eigenen Autorisierungsmodus AuthMode.CUSTOM_FUNCTION, der LIMITED ähnelt, aber geringfügig andere Einschränkungen aufweist. 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, aber im Dokument, Formular, in der Präsentation oder in der Tabelle nicht aktiviert hat)	`onOpen()` (alle anderen Zeiten) `onEdit()` (nur in Google Tabellen)	Benutzerdefinierte Funktionen	Alle anderen Zeiten, einschließlich: installierbare Trigger `onInstall()` `google.script.run`
Zugriff auf Nutzerdaten	Nur Sprache	Nur Sprache	Nur Sprache	Ja
Zugriff auf Dokumente, Formulare, Präsentationen oder Tabellen	Nein	Ja	Ja – schreibgeschützt	Ja
Zugriff auf die Benutzeroberfläche	Artikel auf der Speisekarte hinzufügen	Artikel auf der Speisekarte hinzufügen	Nein	Ja
Der Zugriff auf `Properties`	Nein	Ja	Ja	Ja
Zugriff auf `Jdbc`, `UrlFetch`	Nein	Nein	Ja	Ja
Weitere Leistungen	`Logger` `Utilities`	Alle Dienste, die nicht auf Nutzerdaten zugreifen	Alle 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 das Add-on für das Dokument, das 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 mit der Überwachung der einfachen Trigger onInstall(), onOpen() und onEdit(). 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 seine 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, das Formular, die Präsentation oder die Tabelle bereits geöffnet ist und die onOpen()-Funktion nicht ausgeführt wurde. Das folgende Beispiel zeigt, wie die Funktion onOpen() über die Funktion onInstall() aufgerufen wird:

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, wird jedes Editor-Add-on geladen, das der aktuelle Nutzer installiert hat oder das ein Mitbearbeiter in der Datei aktiviert hat, und ruft jede seiner onOpen()-Funktionen auf. In welchem Autorisierungsmodus onOpen() ausgeführt wird, hängt davon ab, ob ein Add-on installiert oder aktiviert ist.

Wenn ein Add-on nur ein Basismenü erstellt, spielt der Modus keine Rolle. Das folgende Beispiel zeigt eine grundlegende 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 handhaben.

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

Beachten Sie, dass Add-ons während der Ausführung in AuthMode.LIMITED keine Seitenleisten oder Dialogfelder öffnen können. Mit Menüelementen können Sie Seitenleisten und Dialogfelder öffnen, da diese in AuthMode.FULL ausgeführt werden.

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

Wenn ein Nutzer auf einen Menüpunkt Erweiterungen klickt, prüft Apps Script zuerst, ob er das Add-on installiert hat. Ist dies nicht der Fall, wird er dazu aufgefordert. Wenn der Nutzer das Add-on autorisiert hat, führt das Skript die Funktion aus, die dem Menüpunkt in AuthMode.FULL entspricht. Das Add-on ist im Dokument, Formular, der Präsentation oder der Tabelle aktiviert, sofern es nicht bereits aktiviert ist.

Fehlerbehebung, wenn Add-on-Menüs nicht gerendert werden

Ihr Add-on-Menü wird möglicherweise nicht gerendert, wenn der Code die Autorisierungsmodi nicht korrekt verwaltet. 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 mit ihm interagiert.

Führen Sie die folgenden Aktionen aus, um einen Dienstaufruf, der Berechtigungsfehler in AuthMode.NONE verursacht, zu entfernen oder neu anzuordnen:

Ö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, z. B. PropertiesService, SpreadsheetApp oder GmailApp.
Wenn ein Dienst für etwas anderes als zum Erstellen von UI-Elementen verwendet wird, entfernen Sie ihn oder fügen Sie ihn in einen Kommentarblock ein. Behalten Sie nur diese Methoden bei: .getUi(), .createMenu(), .addItem() und .addToUi(). Suchen und entfernen Sie auch alle Dienste, die sich außerhalb einer Funktion befinden.
Identifizieren Sie Funktionen, die Codezeilen enthalten können, die im vorherigen Schritt kommentiert oder entfernt wurden, 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 neu, 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 das Feld Config auf Install for current user (Für aktuellen Nutzer installiert) gesetzt ist und dass im Text unter dem Config-Feld Test in AuthMode.None steht.
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, fahren Sie mit Schritt 1 fort. Möglicherweise haben Sie einen Dienstanruf verpasst.