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 in der Add-on-UI eine Autorisierungsaufforderung angezeigt, um den Autorisierungsprozess zu starten.

Während dieses Prozesses wird dem Nutzer in der Aufforderung mitgeteilt, wofür die Anwendung eine 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 Skriptprojekt des Add-ons werden diese einzelnen Berechtigungen als OAuth-Bereiche definiert.

Sie deklarieren Bereiche in Ihrem Manifest mit URL Strings. Während des Autorisierungsprozesses präsentiert Apps Script dem Nutzer eine für Menschen lesbare Beschreibung des Bereichs. Ihr Add-on verwendet beispielsweise möglicherweise den Bereich „Aktuelles Dokument lesen“, der in Ihrem Manifest als https://www.googleapis.com/auth/documents.currentonly geschrieben ist. Während des Autorisierungsprozesses fordert ein Add-on mit diesem Bereich den Nutzer auf, dem Add-on Folgendes zu erlauben: Dokumente, in denen diese Anwendung installiert wurde, abrufen und verwalten.

Hinweis: Der Bereich currentonly ist nur in Apps Script Diensten verfügbar. Dazu gehören nicht die erweiterten Apps Script Dienste oder direkte Aufrufe von Google Workspace-APIs.

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

Bereiche ansehen

So sehen Sie die Bereiche, die Ihr Skriptprojekt derzeit benötigt:

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 ansehen, unter dem Feld oauthScopes , aber nur, wenn Sie diese Bereiche explizit festgelegt haben.

Explizite Bereiche festlegen

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

Apps Script kann beispielsweise standardmäßig den sehr permissiven Bereich https://mail.google.com für ein Add-on-Skriptprojekt festlegen. Wenn ein Nutzer ein Skriptprojekt mit diesem Bereich autorisiert, erhält das Projekt vollen Zugriff auf das Gmail-Konto des Nutzers. Für veröffentlichte Add-ons müssen Sie diesen Bereich durch eine eingeschränktere Gruppe ersetzen, die die Anforderungen des Add-ons erfüllt und nicht mehr.

Warnung: Verwenden Sie immer die am wenigsten permissive Bereichsgruppe. Zum Schutz von Nutzerinformationen sollten Add-ons und andere veröffentlichte Anwendungen niemals mehr Bereichsberechtigungen anfordern als unbedingt erforderlich. Die Bereiche , die Ihr Add-on benötigt, werden während der Überprüfung des Add-ons für die Veröffentlichung geprüft. Wenn das Add-on zu allgemeine Bereiche verwendet, kann es die Überprüfung nicht bestehen.

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

1. Sehen Sie sich die Bereiche an, die Ihr Add-on verwendet. Bestimmen Sie, welche Änderungen vorgenommen werden müssen, z. B. die Verwendung eines eingeschränkteren Bereichs.
2. Öffnen Sie die Manifestdatei Ihres Add-ons.
3. Suchen Sie das Feld der obersten Ebene mit dem Label oauthScopes. Wenn es nicht vorhanden ist, können Sie es hinzufügen.

4. Das oauthScopes Feld 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 verwendet werden sollen. Für ein Editor-Add-on, das Sheets erweitert, könnte das 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

Für die Verwendung bestimmter sensibler 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 Service: 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, das Add-on zu veröffentlichen. 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: Vermeiden Sie nach Möglichkeit die Verwendung eingeschränkter Bereiche in Ihrem Add-on. Es ist einfacher, die Überprüfung des Add-ons für die öffentliche Veröffentlichung zu bestehen, 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 enthält Diagnoseinformationen für alle Bereiche, einschließlich der Beschreibung des Bereichs und der Angabe, ob er sensibel oder eingeschränkt ist.

Bereiche für Editor-Add-ons

Wenn Sie ein Editor-Add-on erstellen, werden die erforderlichen Bereiche durch den Google 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 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 Bereichserfassung verlassen, anstatt die Bereiche selbst zu bestimmen und explizit festzulegen.

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

/**
 * @OnlyCurrentDoc
 */

Dieser Kommentar weist Apps Script an, die für die Editor-Datei festgelegten Bereiche auf currentonly zu beschränken. Wenn Sie diesen Kommentar beispielsweise einer Skriptprojektdatei für ein Sheets-Add-on hinzufügen, geben Sie an, dass das Add-on nur die Berechtigung benötigt, in der geöffneten Tabelle zu arbeiten, und nicht in anderen Tabellen, die der Nutzer möglicherweise in Google Drive hat. Umgekehrt sollten Sie diesen Kommentar nicht verwenden, wenn Ihr Sheets-Add-on Daten in einer Tabelle lesen oder schreiben muss, die der Nutzer nicht geöffnet hat.

Hinweis: Der Bereich currentonly ist nur in Apps Script Diensten verfügbar. Dazu gehören nicht die erweiterten Apps Script Dienste oder direkte Aufrufe von Google Workspace-APIs.