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-UI eine Autorisierungsaufforderung angezeigt, über die der Autorisierungsvorgang gestartet werden kann.

Während dieses Ablaufs teilt die Eingabeaufforderung dem Nutzer mit, für welche Berechtigung die Anwendung die Berechtigung benötigt. Ein Add-on kann beispielsweise die Berechtigung anfordern, die E-Mail-Nachricht eines Nutzers zu lesen oder Termine in seinem Kalender zu erstellen. Im Skriptprojekt des Add-ons werden diese einzelnen Berechtigungen als OAuth-Bereiche definiert.

Bereiche deklarieren Sie in Ihrem Manifest mithilfe von URL-Strings. Während des Autorisierungsvorgangs zeigt Apps Script dem Nutzer eine für Menschen lesbare Beschreibung des Umfangs an. Ihr Add-on kann beispielsweise den Bereich „Aktuelles Dokument lesen“ verwenden, der in Ihrem Manifest als https://www.googleapis.com/auth/documents.currentonly geschrieben ist. Während des Autorisierungsvorgangs fordert ein Add-on mit diesem Bereich den Nutzer auf, dem Add-on folgende Berechtigungen zu erteilen: Dokumente aufrufen und verwalten, in denen diese Anwendung installiert wurde.

Hinweis :Die Bereiche, die Apps Script für seine verschiedenen Dienste verwendet, überschneiden sich mit den Bereichen, die von der zugehörigen API verwendet werden. Der Kalenderdienst von Apps Script nutzt beispielsweise viele Bereiche, in denen die Calendar API verwendet wird. Die Bereiche, die bestimmte Apps Script-Dienstmethoden benötigen, finden Sie in der Referenzdokumentation zu Apps Script.

Bereiche ansehen

Sie können die Bereiche sehen, die Ihr Skriptprojekt derzeit benötigt. Gehen Sie dazu so vor:

1. Öffnen Sie das Skriptprojekt.
2. Klicken Sie links auf Übersicht .
3. Sehen Sie sich die Bereiche unter „OAuth-Bereiche des Projekts“ an.

Sie können die aktuellen Bereiche des Skriptprojekts auch im Projektmanifest unter dem Feld oauthScopes aufrufen, aber nur dann, wenn Sie diese Bereiche explizit festgelegt haben.

Explizite Bereiche festlegen

Apps Script ermittelt automatisch, welche Bereiche ein Skript benötigt, indem es den Code auf Funktionsaufrufe scannt, die diese erfordern. Bei den meisten Skripts ist dies ausreichend und spart Zeit. Bei veröffentlichten Add-ons sollten Sie jedoch die Bereiche direkter kontrollieren.

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

Warnung: Verwenden Sie immer den minimal verfügbaren Bereichssatz. Zum Schutz von Nutzerinformationen sollten Add-ons und andere veröffentlichte Anwendungen nie mehr Berechtigungen anfordern, als sie unbedingt benötigen. Die für Ihr Add-on erforderlichen Bereiche werden bei der Add-on-Überprüfung der Veröffentlichung untersucht. Wenn das Add-on zu weit gefasste Bereiche verwendet, kann es die Überprüfung nicht bestehen.

Sie können die von Ihrem Skriptprojekt verwendeten Bereiche explizit festlegen, indem Sie die Manifestdatei bearbeiten. Das Manifestfeld oauthScopes ist ein Array aller vom Add-on verwendeten Bereiche. So legen Sie die Bereiche Ihres Projekts fest:

1. Sehen Sie sich an, welche Bereiche das Add-on derzeit verwendet. Bestimmen Sie, welche Änderungen vorgenommen werden müssen, z. B. durch einen enger gefassten Anwendungsbereich.
2. Öffnen Sie die Manifestdatei des Add-ons.
3. Suchen Sie das oberste Feld mit der Bezeichnung oauthScopes. Ist er nicht vorhanden, können Sie ihn hinzufügen.

4. Das Feld oauthScopes gibt ein Array von Strings an. Um die von Ihrem Projekt verwendeten Bereiche festzulegen, ersetzen Sie den Inhalt dieses Arrays durch die Bereiche, die es verwenden soll. Für ein Editor-Add-on, das Google Tabellen erweitert, könnten Sie beispielsweise Folgendes haben:

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

5. Speichern Sie die Änderungen an der Manifestdatei.

OAuth-Überprüfung

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

• OAuth-Client-Überprüfung für Apps Script
• Nicht verifizierte Apps
• Häufig gestellte Fragen zur OAuth-Bestätigung
• Google APIs-Dienst: Nutzerdatenrichtlinie

Eingeschränkte Bereiche

Bestimmte Bereiche sind eingeschränkt und unterliegen zusätzlichen Regeln zum Schutz von Nutzerdaten. Wenn Sie ein Gmail- oder Editor-Add-on veröffentlichen möchten, das einen oder mehrere eingeschränkte Bereiche verwendet, muss das Add-on vor der Veröffentlichung alle angegebenen Einschränkungen erfüllen.

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

Hinweis :Verwenden Sie nach Möglichkeit eingeschränkte Bereiche in Ihrem Add-on. Andernfalls ist es einfacher, die Add-on-Prüfung für die öffentliche Veröffentlichung zu bestehen. Sie können eingeschränkte Bereiche frei für nicht öffentliche Add-ons verwenden.

Editor-Add-on-Bereiche

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

Apps Script ermittelt automatisch die Bereiche, die von den Diensten benötigt werden, die Sie verwenden, wenn Sie Code zu Ihrem Skriptprojekt hinzufügen. Bei Editor-Add-ons können Sie sich häufig nur auf diese automatische Bereichserfassung verlassen, anstatt die Bereiche selbst zu bestimmen und explizit festzulegen.

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

  /**
   * @OnlyCurrentDoc
   */

Dieser Kommentar weist Apps Script an, die Bereiche der Editordatei einzuschränken, die auf currentonly festgelegt werden. Wenn Sie diesen Kommentar beispielsweise einer Projektdatei mit einem Add-on-Skript für Google Tabellen hinzufügen, geben Sie an, dass das Add-on nur die Berechtigung für das aktuell geöffnete Tabellenblatt benötigt und keine anderen Tabellen, die der Nutzer in Google Drive hat. Umgekehrt sollten Sie diesen Kommentar nicht verwenden, wenn Ihr Tabellen-Add-on Daten in einem Tabellenblatt lesen oder schreiben muss, das der Nutzer derzeit nicht geöffnet hat.