Autorisierungsbereiche für Editor-Add-ons

Nutzer müssen Add-ons und andere Anwendungen autorisieren, die auf ihre Daten zugreifen oder in ihrem Namen handeln. Wenn ein Nutzer ein Add-on zum ersten Mal ausführt, wird auf der Add-on-Benutzeroberfläche eine Autorisierungsaufforderung angezeigt, um den Autorisierungsablauf zu starten.

Während dieses Vorgangs wird dem Nutzer in der Aufforderung mitgeteilt, für welche Aktion die App die Berechtigung benötigt. Ein Add-on benötigt beispielsweise möglicherweise die Berechtigung, die E-Mail-Nachricht eines Nutzers zu lesen oder Termine in seinem Kalender zu erstellen. Im Script-Projekt des Add-ons werden diese individuellen Berechtigungen als OAuth-Bereiche definiert.

Sie deklarieren Bereiche in Ihrem manifest mithilfe von URL-Strings. Während des Autorisierungsvorgangs wird dem Nutzer in Apps Script eine visuell lesbare Beschreibung des Bereichs angezeigt. Ihr Add-on kann beispielsweise den Umfang „Aktuelles Dokument lesen“ verwenden, der in Ihrem Manifest als https://www.googleapis.com/auth/documents.currentonly geschrieben ist. Während des Autorisierungsvorgangs wird der Nutzer von einem Add-on mit diesem Umfang gefragt, ob er dem Add-on Folgendes erlauben möchte: Dokumente, in denen diese Anwendung installiert wurde, abrufen und verwalten

Bereiche ansehen

So rufen Sie die Bereiche auf, die für Ihr Scriptprojekt derzeit erforderlich sind:

  1. Öffnen Sie das Script-Projekt.
  2. Klicken Sie links auf Übersicht .
  3. Sie finden die Bereiche unter „OAuth-Bereiche des Projekts“.

Sie können sich die aktuellen Bereiche des Scriptprojekts auch im Projektmanifest im Feld oauthScopes ansehen, aber nur, wenn Sie diese Bereiche explizit festgelegt haben.

Explizite Bereiche festlegen

In Apps Script wird automatisch ermittelt, welche Bereiche ein Script benötigt. Dazu wird der Code nach Funktionsaufrufen gescannt, für die sie erforderlich sind. Für die meisten Scripts ist das ausreichend und spart Zeit. Bei veröffentlichten Add-ons sollten Sie jedoch die Berechtigungen direkter verwalten.

So kann Apps Script einem Add-on-Scriptprojekt standardmäßig den sehr weitreichenden Umfang https://mail.google.com zuweisen. Wenn ein Nutzer ein Scriptprojekt mit diesem Umfang autorisiert, erhält das Projekt vollen Zugriff auf das Gmail-Konto des Nutzers. Bei veröffentlichten Add-ons müssen Sie diesen Umfang durch einen eingeschränkteren ersetzen, der nur die Anforderungen der Add-ons erfüllt.

Sie können die Bereiche, die in Ihrem Scriptprojekt verwendet werden, explizit festlegen, indem Sie die manifest bearbeiten. Das Manifest-Feld oauthScopes ist ein Array aller Bereiche, die vom Add-on verwendet werden. So legen Sie die Bereiche Ihres Projekts fest:

  1. Hier sehen Sie die Bereiche, die Ihr Add-on derzeit verwendet. Ermitteln Sie, welche Änderungen erforderlich sind, z. B. einen engeren Umfang.
  2. Öffnen Sie die Manifestdatei Ihres Add-ons.
  3. Suchen Sie das Feld der obersten Ebene mit der Bezeichnung oauthScopes. Wenn sie nicht vorhanden ist, können Sie sie hinzufügen.

  4. Im Feld oauthScopes wird ein Array von Strings angegeben. Wenn Sie die Bereiche festlegen möchten, die in Ihrem Projekt verwendet werden, ersetzen Sie den Inhalt dieses Arrays durch die gewünschten Bereiche. Für ein Editor-Add-on, das Google Tabellen erweitert, könnte das beispielsweise so aussehen:

    {
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.container.ui",
    "https://www.googleapis.com/auth/spreadsheets"
  ],
  ...
}

  5. Speichern Sie die Änderungen an der Manifestdatei.

OAuth-Überprüfung

Wenn Sie bestimmte vertrauliche OAuth-Bereiche verwenden, muss Ihr Add-on möglicherweise OAuth-Client-Überprüfungen durchlaufen, bevor Sie es veröffentlichen können. Weitere Informationen finden Sie in folgenden Leitfäden:

Eingeschränkter Geltungsbereich

Bestimmte Bereiche sind eingeschränkt und unterliegen zusätzlichen Regeln, die zum Schutz von Nutzerdaten beitragen. Wenn Sie ein Gmail- oder Editor-Add-on veröffentlichen möchten, das eine oder mehrere eingeschränkte Bereiche verwendet, muss das Add-on alle angegebenen Einschränkungen erfüllen, bevor es veröffentlicht werden kann.

Sehen Sie sich die vollständige Liste der eingeschränkten Bereiche an, bevor Sie versuchen, etwas zu veröffentlichen. Wenn Ihr Add-on eine dieser APIs verwendet, müssen Sie vor der Veröffentlichung die zusätzlichen Anforderungen für bestimmte API-Bereiche erfüllen.

Bereiche für Editor-Add-ons

Wenn Sie ein Editor-Add-on erstellen, werden die erforderlichen Bereiche vom App Script-Dienst und den Methoden bestimmt, die im Add-on-Code verwendet werden. Ein Google Tabellen-Add-on benötigt beispielsweise den Bereich https://www.googleapis.com/auth/spreadsheets.readonly, um Informationen aus verschiedenen Google-Tabellen zu lesen.

In Apps Script werden die für die von Ihnen verwendeten Dienste erforderlichen Bereiche automatisch ermittelt, wenn Sie Ihrem Scriptprojekt Code hinzufügen. Bei Editor-Add-ons können Sie oft einfach auf diese automatische Erfassung des Gültigkeitsbereichs zurückgreifen, anstatt die Gültigkeitsbereiche selbst zu ermitteln und explizit festzulegen.

Wenn Sie Ihre Bereiche nicht explizit festlegen und Ihr Editor-Add-on nur die geöffnete Editordatei liest oder in sie schreibt, fügen Sie einer Ihrer Scriptprojektdateien den folgenden Kommentar hinzu:

  /**
   * @OnlyCurrentDoc
   */

Mit diesem Kommentar wird Apps Script angewiesen, den Gültigkeitsbereich der Editordateien auf currentonly einzugrenzen. Wenn Sie diesen Kommentar beispielsweise einer Projektdatei für ein Google Sheets-Add-on-Script hinzufügen, geben Sie an, dass das Add-on nur für die aktuell geöffnete Tabelle und nicht für andere Tabellen, die der Nutzer in Google Drive haben könnte, berechtigt sein muss. Umgekehrt sollten Sie diesen Kommentar nicht verwenden, wenn Ihr Google Tabellen-Add-on Daten in einem Tabellenblatt lesen oder schreiben muss, das der Nutzer derzeit nicht geöffnet hat.