Autorisierungsbereiche für Editor-Add-ons

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

Während dieses Ablaufs wird dem Nutzer mitgeteilt, welche Berechtigungen die Anwendung 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 Skriptprojekt des Add-ons werden diese einzelnen Berechtigungen als OAuth-Bereiche definiert.

Sie deklarieren Bereiche in Ihrem Manifest mithilfe von URL-Strings. Während des Autorisierungsablaufs wird dem Nutzer in Apps Script eine für Menschen lesbare Beschreibung des Bereichs angezeigt. Ihr Add-on verwendet beispielsweise den Bereich „Aktuelles Dokument lesen“, der in Ihrem Manifest als https://www.googleapis.com/auth/documents.currentonly angegeben ist. Während des Autorisierungsvorgangs wird der Nutzer bei einem Add-on mit diesem Bereich aufgefordert, dem Add-on die folgenden Berechtigungen zu erteilen: Dokumente, in denen diese Anwendung installiert wurde, abrufen und verwalten.

Hinweis:Der Bereich currentonly ist nur in Apps Script-Diensten verfügbar. Das gilt nicht für erweiterte Apps Script-Dienste oder direkte Aufrufe von Google Workspace-APIs.

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 Calendar-Dienst von Apps Script verwendet beispielsweise viele der gleichen Bereiche wie die Calendar API. Die für bestimmte Apps Script-Dienstmethoden erforderlichen Bereiche finden Sie in der Apps Script-Referenzdokumentation.

Bereiche ansehen

So können Sie die Berechtigungsbereiche sehen, die für Ihr Skriptprojekt derzeit erforderlich sind:

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

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

Explizite Bereiche festlegen

Apps Script ermittelt automatisch, welche Bereiche für ein Skript erforderlich sind, indem der Code nach Funktionsaufrufen gescannt wird, für die sie benötigt werden. Für die meisten Scripts ist das ausreichend und spart Ihnen Zeit. Bei veröffentlichten Add-ons sollten Sie jedoch mehr direkte Kontrolle über die Bereiche haben.

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

Warnung :Verwenden Sie immer den geringstmöglichen Berechtigungssatz. Zum Schutz von Nutzerinformationen sollten Add-ons und andere veröffentlichte Anwendungen niemals mehr Berechtigungen für Bereiche anfordern, als unbedingt erforderlich sind. Die für Ihr Add-on erforderlichen Bereiche werden während der Überprüfung von Add-ons im Rahmen 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. Bereiche ansehen, die von Ihrem Add-on derzeit verwendet werden Legen Sie fest, welche Änderungen vorgenommen werden müssen, z. B. die Verwendung eines engeren Bereichs.
2. Manifestdatei des Add-ons öffnen
3. Suchen Sie das Feld der obersten Ebene mit dem Label oauthScopes. Wenn sie nicht vorhanden ist, können Sie sie hinzufügen.

4. Das Feld oauthScopes gibt ein Array von Strings an. Wenn Sie die Bereiche festlegen möchten, die Ihr Projekt verwendet, ersetzen Sie den Inhalt dieses Arrays durch die Bereiche, die Sie verwenden möchten. 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"
     ],
     ...
   }
   

5. Speichern Sie die Änderungen an der Manifestdatei.

OAuth-Überprüfung

Für die Verwendung bestimmter vertraulicher OAuth-Bereiche muss Ihr Add-on möglicherweise 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 überprüfte Apps
• Häufig gestellte Fragen zur OAuth-Überprüfung
• Google APIs-Dienste: Nutzerdatenrichtlinie

Eingeschränkte Bereiche

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 einen 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, die App 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.

Hinweis :Vermeiden Sie die Verwendung eingeschränkter Bereiche in Ihrem Add-on, wenn möglich. Die Add-on-Überprüfung für die öffentliche Veröffentlichung ist einfacher, wenn Sie sie nicht verwenden. Sie können eingeschränkte Bereiche für nicht öffentliche Add-ons frei verwenden.

Die Google Workspace Developer Tools-Erweiterung für Visual Studio Code bietet Diagnoseinformationen für alle Bereiche, einschließlich der Beschreibung des Bereichs und der Angabe, ob er vertraulich oder eingeschränkt ist.

Bereiche für Editor-Add-ons

Wenn Sie ein Editor-Add-on erstellen, werden die erforderlichen Bereiche durch den Apps Script-Dienst und die Methoden bestimmt, die im Add-on-Code verwendet werden. Ein Google Sheets-Add-on benötigt beispielsweise 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 für die von Ihnen verwendeten Dienste erforderlich sind, wenn Sie Ihrem Skriptprojekt Code hinzufügen. Bei Editor-Add-ons können Sie sich oft einfach auf diese automatische Erfassung von Bereichen verlassen, anstatt die Bereiche selbst zu bestimmen und explizit festzulegen.

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

  /**
   * @OnlyCurrentDoc
   */

Dieser Kommentar weist Apps Script an, die von ihm festgelegten Editor-Dateibereiche auf currentonly zu beschränken. 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 die Berechtigung benötigt, auf das aktuell geöffnete Tabellenblatt zuzugreifen, und nicht auf andere Tabellenblätter, die der Nutzer möglicherweise in Google Drive hat. Umgekehrt sollten Sie diesen Kommentar nicht verwenden, wenn Ihr Google Sheets-Add-on Daten in einer Tabelle lesen oder schreiben muss, die der Nutzer derzeit nicht geöffnet hat.

Hinweis:Der Bereich currentonly ist nur in Apps Script-Diensten verfügbar. Das gilt nicht für erweiterte Apps Script-Dienste oder direkte Aufrufe von Google Workspace-APIs.