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 Autorisierungsvorgang zu starten.
Während dieses Ablaufs wird dem Nutzer mitgeteilt, wozu die Anwendung 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 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.
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 Apps Script-Kalenderdienst verwendet beispielsweise viele der gleichen Bereiche wie die Calendar API. Die erforderlichen Bereiche für bestimmte Apps Script-Dienstmethoden finden Sie in der Apps Script-Referenzdokumentation.
Bereiche ansehen
So können Sie die Berechtigungsbereiche sehen, die für Ihr Skriptprojekt derzeit erforderlich sind:
- Öffnen Sie das Skriptprojekt.
- Klicken Sie links auf Übersicht .
- Die Bereiche finden Sie unter „Project OAuth Scopes“ (OAuth-Bereiche für das Projekt).
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 Skripts ist das ausreichend und spart Ihnen Zeit. Bei veröffentlichten Add-ons sollten Sie jedoch mehr direkte Kontrolle über die Bereiche haben.
In Apps Script wird einem Add-on-Scriptprojekt beispielsweise standardmäßig der sehr permissive Bereich https://mail.google.com zugewiesen. Wenn ein Nutzer ein Skriptprojekt 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.
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:
- Bereiche ansehen, die von Ihrem Add-on verwendet werden Legen Sie fest, welche Änderungen vorgenommen werden müssen, z. B. die Verwendung eines engeren Geltungsbereichs.
- Manifestdatei des Add-ons öffnen
- Suchen Sie das Feld der obersten Ebene mit dem Label
oauthScopes. Wenn sie nicht vorhanden ist, können Sie sie hinzufügen. Das Feld
oauthScopesgibt 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" ], ... }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 bestätigte Apps
- Häufig gestellte Fragen zur OAuth-Überprüfung
- Google APIs-Dienste: Richtlinie zu Nutzerdaten
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, Ihre App 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.
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 Frage, 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 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 Scriptprojekt 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 Script-Projektdateien 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 Scriptprojektdatei für ein Google Sheets-Add-on hinzufügen, geben Sie an, dass das Add-on nur die Berechtigung benötigt, um auf die geöffnete Tabelle zuzugreifen, und nicht auf andere Tabellen, 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 nicht geöffnet hat.