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 verschiedenen Gründen komplexer:

• Wenn ein Nutzer eine Datei erstellt, werden alle Add-ons, die er installiert hat, hinzugefügt. sind im Menü Erweiterungen aufgeführt, auch wenn wenn der Nutzer diese Add-ons noch nicht autorisiert hat.

• Diese Add-ons funktionieren bei Dateien in Google Drive, das für Mitbearbeiter freigegeben werden kann. Mitbearbeiter, die dies nicht tun Wenn Sie das Editor-Add-on installiert haben, sehen Sie es in Dokumenten. wo sie vom Ersteller der Datei verwendet wurde.

• Editor-Add-ons führen automatisch ihre onOpen() aus wie 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 ist.

• Ein Add-on wird für eine bestimmte nachdem sie oder ihr Administrator sie aus dem Google Workspace Marketplace autorisieren und ihn für den Zugriff auf Google-Daten autorisieren.
• 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 sind 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 schränkt Apps Script ein, was die onOpen(). Status des Editor-Add-ons legt fest, in welchem Autorisierungsmodus die Funktion onOpen() ausgeführt wird.

Wenn ein Editor-Add-on in der Datei aktiviert ist, Formular, Präsentation oder Tabelle, onOpen() wird ausgeführt in AuthMode.LIMITED. 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 bis der Nutzer mit dem Add-on interagiert, indem er auf benutzerdefinierte Funktionen klicken oder ausführen. 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.

Apps Script übergibt den Autorisierungsmodus als authMode-Eigenschaft des Apps Scripts Ereignisparameter, e; der Wert von e.authMode entspricht einer Konstante im Apps Script ScriptApp.AuthMode-Enum.

Autorisierungsmodi gelten für alle Apps Script-Ausführungsmethoden, z. B. über den Script-Editor, einen Menüpunkt oder ein Apps Script google.script.run-Anruf. Sie können jedoch Das Attribut e.authMode kann nur geprüft werden, wenn das Script als Ergebnis ausgeführt wird eines Triggers wie onOpen(), onEdit() oder onInstall(). Benutzerdefinierte Funktionen in Google Tabellen einen eigenen Autorisierungsmodus verwenden, AuthMode.CUSTOM_FUNCTION, Dieser ist LIMITED ähnlich, hat aber leicht andere Einschränkungen. Für alle In anderen Fällen werden Skripts in AuthMode.FULL ausgeführt, wie im Folgenden beschrieben .

Autorisierungslebenszyklus 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 ist Erweiterungen und beginnt, die Ereignisse einfachen Triggern onInstall() onOpen() und onEdit(). Wenn ein Nutzer auf eine Erweiterungen enthält, wird sie ausgeführt.

Das Editor-Add-on ist installiert.

Wenn ein Editor-Add-on aus dem Store installiert wird, Die Funktion onInstall() wird in AuthMode.FULL ausgeführt. In diesem Autorisierungsmodus das Add-on kann eine komplexe Einrichtungsroutine ausführen. Außerdem sollten Sie onInstall() zum Erstellen von Menüpunkten verwenden, da das Dokument, das Formular, die Präsentation oder die Tabelle bereits geöffnet ist und die Funktion onOpen() 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 grundlegende 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, Apps Script prüft zuerst, ob der Nutzer die Add-on und und fordert sie auf, dies zu tun. Wenn der Nutzer die das Skript die Funktion aus, entspricht dem Menüpunkt in AuthMode.FULL. Die ist im Dokument, im Formular, im Formular Präsentation oder Tabellenkalkulation, falls dies noch nicht der Fall war.

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

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

Um einen Dienstaufruf, der Berechtigungsfehler verursacht, in AuthMode.NONE versuchen Sie Folgendes:

1. Öffnen Sie das Apps Script-Projekt für Ihr Add-on und suchen Sie die Funktion onOpen().
2. In der onOpen()-Funktion nach Erwähnungen von Apps Script suchen Dienste oder Objekte, die damit verknüpft sind, wie z. B. 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. Behalten Sie nur die folgenden Methoden bei: .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 das Feld Config Installiert für aktuellen Nutzer und unter dem Konfigurationsfeld steht Test in AuthMode.None

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

7. Wenn alle Menüpunkte angezeigt werden, ist das Problem behoben. Wenn Sie nur das Menü Hilfe sehen, gehen Sie zurück zu Schritt 1. Möglicherweise haben Sie einen Serviceanruf verpasst.

Weitere Informationen

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