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 teilt die Eingabeaufforderung dem Nutzer mit, was die Anwendung tun soll. Beispielsweise kann ein Add-on die Berechtigung zum Lesen der E-Mail-Nachricht eines Nutzers oder zum Erstellen von Terminen in seinem Kalender anfordern. 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. Das Google Workspace-Add-on kann beispielsweise den Bereich „Aktuelle Nachricht lesen“ verwenden, der in Ihrem Manifest als https://www.googleapis.com/auth/gmail.addons.current.message.readonly
geschrieben ist. Während des Autorisierungsvorgangs wird der Nutzer von einem Add-on mit diesem Umfang gefragt, ob er dem Add-on erlauben möchte, seine E-Mails abzurufen, während das Add-on ausgeführt wird.
Bereiche ansehen
So rufen Sie die Bereiche auf, die für Ihr Scriptprojekt derzeit erforderlich sind:
- Öffnen Sie das Script-Projekt.
- Klicken Sie links auf Übersicht .
- 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
ansehen, allerdings nur, wenn Sie diese Bereiche explizit festgelegt haben.
Explizite Bereiche festlegen
Apps Script ermittelt automatisch, welche Bereiche ein Skript benötigt, indem es seinen Code auf Funktionsaufrufe scannt, die diese Bereiche erfordern. 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 Ihr Skriptprojekt verwendet, 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:
- Aktuell vom Add-on verwendete Bereiche ansehen Ermitteln Sie, welche Änderungen erforderlich sind, z. B. einen engeren Umfang.
- Öffnen Sie die Manifestdatei Ihres Add-ons.
- Suchen Sie das Feld der obersten Ebene mit der Bezeichnung
oauthScopes
. Wenn sie nicht vorhanden ist, können Sie sie hinzufügen. Das Feld
oauthScopes
gibt ein String-Array an. Wenn Sie die Bereiche festlegen möchten, die in Ihrem Projekt verwendet werden, ersetzen Sie den Inhalt dieses Arrays durch die gewünschten Bereiche. Ein Google Workspace-Add-on zur Erweiterung von Gmail könnte beispielsweise Folgendes enthalten:{ ... "oauthScopes": [ "https://www.googleapis.com/auth/gmail.addons.current.message.metadata", "https://www.googleapis.com/auth/userinfo.email" ], ... }
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:
- OAuth-Clientüberprüfung für Apps Script
- Nicht überprüfte Apps
- Häufig gestellte Fragen zur OAuth-Verifizierung
- Google APIs-Dienst: Richtlinie zu Nutzerdaten
Eingeschränkter Geltungsbereich
Bestimmte Bereiche sind eingeschränkt und unterliegen zusätzlichen Regeln zum Schutz der 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 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.
Gültigkeitsbereich für Google Workspace-Add-ons auswählen
Die folgenden Abschnitte enthalten Bereiche, die häufig für Google Workspace-Add-ons verwendet werden.
Bearbeitungsbereiche
Im Folgenden finden Sie häufig verwendete Bereiche für Google Workspace-Add-ons, die Google Docs, Google Tabellen und Google Präsentationen erweitern.
Umfang | |
---|---|
Aktueller Zugriff auf Google Docs-Dateien |
https://www.googleapis.com/auth/documents.currentonly
Erforderlich, wenn das Add-on auf die Apps Script Docs API zugreift. Gewährt vorübergehenden Zugriff auf den Inhalt des geöffneten Dokuments. |
Aktueller Zugriff auf Google Tabellen-Dateien |
https://www.googleapis.com/auth/spreadsheets.currentonly
Erforderlich, wenn das Add-on auf die Sheets API von Apps Script zugreift. Gewährt vorübergehenden Zugriff auf den Inhalt der geöffneten Tabelle. |
Aktueller Zugriff auf Google Präsentationen-Dateien |
https://www.googleapis.com/auth/presentations.currentonly
Erforderlich, wenn das Add-on auf die Apps Script-Präsentationen API zugreift. Gewährt vorübergehenden Zugriff auf die Inhalte der geöffneten Präsentation. |
Zugriff pro Datei |
https://www.googleapis.com/auth/drive.file
Erforderlich, damit das Add-on die |
Gmail
Es gibt einige Bereiche, die speziell für Google Workspace-Add-ons erstellt wurden, um die Gmail-Daten der Nutzer zu schützen. Diese Bereiche müssen Ihrem Add-on-Manifest explizit hinzugefügt werden, ebenso wie andere Bereiche, die für den Add-on-Code erforderlich sind.
Im Folgenden finden Sie häufig verwendete Bereiche für Google Workspace-Add-ons, die Gmail erweitern. Die mit Erforderlich gekennzeichneten Bereiche müssen dem Manifest Ihres Google Workspace-Add-ons hinzugefügt werden, wenn Ihr Add-on Gmail erweitert.
Ersetzen Sie außerdem den sehr weit gefassten Bereich https://mail.google.com
in Ihrem Add-on durch einen engeren Bereich, der nur die Interaktionen zulässt, die für Ihr Add-on erforderlich sind.
Umfang | |
---|---|
Neue Entwürfe erstellen |
https://www.googleapis.com/auth/gmail.addons.current.action.compose
Erforderlich, wenn das Add-on Trigger für zusammengesetzte Aktionen verwendet. Ermöglicht es dem Add-on, vorübergehend neue Nachrichtenentwürfe und Antworten zu erstellen. Weitere Informationen finden Sie unter Nachrichtenentwürfe verfassen. Dieser Bereich wird auch häufig zusammen mit Schreibaktionen verwendet. Erfordert ein Zugriffstoken. |
Metadaten der geöffneten Nachricht lesen |
https://www.googleapis.com/auth/gmail.addons.current.message.metadata
Gewährt temporären Zugriff auf die Metadaten der geöffneten Nachricht, z. B. auf den Betreff oder die Empfänger. Ermöglicht nicht das Lesen von Nachrichteninhalten und erfordert ein Zugriffstoken. Erforderlich, wenn das Add-on Metadaten in Triggern für die Aktion „Compose“ verwendet. Für Aufrufaktionen ist dieser Umfang erforderlich, wenn ein Trigger für den Aufruf Zugriff auf Metadaten benötigt. In der Praxis ermöglicht dieser Umfang dem Verfasser, die Empfängerlisten (An:, Cc: und Bcc:) eines E-Mail-Entwurfs zu öffnen. |
Inhalt geöffneter Nachrichten lesen |
https://www.googleapis.com/auth/gmail.addons.current.message.action
Gewährt Zugriff auf den Inhalt der geöffneten Nachricht bei einer Nutzerinteraktion, z. B. wenn ein Menüpunkt für ein Add-on ausgewählt wird. Erfordert ein Zugriffstoken. |
Inhalte eines offenen Threads lesen |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly
Gewährt vorübergehenden Zugriff auf die Metadaten und den Inhalt der geöffneten Nachricht. Gewährt auch Zugriff auf den Inhalt anderer Nachrichten im geöffneten Thread. Erfordert ein Zugriffstoken. |
Nachrichteninhalte und Metadaten lesen |
https://www.googleapis.com/auth/gmail.readonly
Lesen von E-Mail-Metadaten und -Inhalten, einschließlich der geöffneten Nachricht Erforderlich, wenn Sie Informationen zu anderen Nachrichten lesen möchten, z. B. wenn Sie eine Suchanfrage stellen oder einen gesamten E-Mail-Thread lesen. |
Google Kalender-Bereiche
Im Folgenden finden Sie häufig verwendete Bereiche für Google Workspace-Add-ons, die Google Kalender erweitern.
Umfang | |
---|---|
Auf Ereignismetadaten zugreifen |
https://www.googleapis.com/auth/calendar.addons.execute
Erforderlich, wenn das Add-on auf Metadaten von Kalenderterminen zugreift. Ermöglicht dem Add-on den Zugriff auf Ereignismetadaten. |
Von Nutzern erstellte Ereignisdaten lesen |
https://www.googleapis.com/auth/calendar.addons.current.event.read
Erforderlich, wenn das Add-on von Nutzern erstellte Ereignisdaten lesen muss.
Ermöglicht dem Add-on den Zugriff auf von Nutzern generierte Ereignisdaten. Diese Daten sind nur verfügbar, wenn das |
Nutzergenerierte Ereignisdaten schreiben |
https://www.googleapis.com/auth/calendar.addons.current.event.write
Erforderlich, wenn das Add-on nutzergenerierte Ereignisdaten schreiben muss.
Ermöglicht dem Add-on, von Nutzern generierte Ereignisdaten zu bearbeiten. Diese Daten sind nur verfügbar, wenn das |
Google Drive-Bereiche
Im Folgenden finden Sie häufig verwendete Bereiche für Google Workspace-Add-ons, die Google Drive erweitern.
Umfang | |
---|---|
Metadaten des ausgewählten Artikels lesen |
https://www.googleapis.com/auth/drive.addons.metadata.readonly
Erforderlich, wenn das Add-on eine kontextbezogene Benutzeroberfläche implementiert, die ausgelöst wird, wenn der Nutzer Elemente in Drive auswählt. Ermöglicht dem Add-on, eingeschränkte Metadaten zu Elementen zu lesen, die ein Nutzer in Google Drive ausgewählt hat. Die Metadaten sind auf die ID, den Titel, den MIME-Typ und die Symbol-URL des Elements beschränkt. Außerdem gibt es nur eine Zugriffsberechtigung für das Add-on. |
Zugriff pro Datei |
https://www.googleapis.com/auth/drive.file
Empfohlen, wenn das Add-on auf einzelne Drive-Dateien zugreifen muss.
Gewährt pro Datei Zugriff auf Dateien, die von der App erstellt oder geöffnet wurden, mithilfe des erweiterten Drive-Dienstes von Apps Script. Die Verwendung ähnlicher Aktionen über den einfachen Drive-Dienst ist jedoch nicht möglich. Die Dateiautorisierung wird pro Datei gewährt und aufgehoben, wenn der Nutzer die App deaktiviert. |
Zugriffstokens
Zum Schutz von Nutzerdaten gewähren die in Google Workspace-Add-ons verwendeten Gmail-Bereiche nur vorübergehenden Zugriff auf Nutzerdaten. Sie müssen die Funktion GmailApp.setCurrentMessageAccessToken(accessToken)
mit einem Zugriffstoken als Argument aufrufen, um den temporären Zugriff zu ermöglichen. Sie benötigen ein Zugriffstoken von einem Aktionsereignisobjekt.
Im folgenden Beispiel wird ein Zugriffstoken festgelegt, um den Zugriff auf die Metadaten einer Nachricht zu ermöglichen. Für dieses Beispiel ist nur https://www.googleapis.com/auth/gmail.addons.current.message.metadata
erforderlich.
function readSender(e) {
var accessToken = e.gmail.accessToken;
var messageId = e.gmail.messageId;
// The following function enables short-lived access to the current
// message in Gmail. Access to other Gmail messages or data isn't
// permitted.
GmailApp.setCurrentMessageAccessToken(accessToken);
var mailMessage = GmailApp.getMessageById(messageId);
return mailMessage.getFrom();
}
Andere Google Workspace-Bereiche
Für Ihr Add-on sind möglicherweise zusätzliche Bereiche erforderlich, wenn andere Google Workspace- oder Apps Script-Dienste verwendet werden. In den meisten Fällen können Sie Apps Script diese Bereiche erkennen und das Manifest automatisch aktualisieren lassen. Entfernen Sie beim Bearbeiten der Gültigkeitsliste Ihres Manifests nur Gültigkeitsbereiche, wenn Sie sie durch eine geeignetere Alternative ersetzen, z. B. durch einen engeren Gültigkeitsbereich.
Die folgende Tabelle zeigt eine Liste der Bereiche, die häufig von Google Workspace-Add-ons verwendet werden:
Umfang | |
---|---|
E-Mail-Adresse des Nutzers lesen |
https://www.googleapis.com/auth/userinfo.email
Ermöglicht dem Projekt, die E-Mail-Adresse des aktuellen Nutzers zu lesen. |
Aufrufe externer Dienste zulassen |
https://www.googleapis.com/auth/script.external_request
Ermöglicht dem Projekt, |
Gebietsschema und Zeitzone des Nutzers lesen |
https://www.googleapis.com/auth/script.locale
Ermöglicht dem Projekt, die Sprache und Zeitzone des aktuellen Nutzers zu ermitteln. Weitere Informationen finden Sie unter Auf die Sprache und Zeitzone des Nutzers zugreifen. |
Trigger erstellen |
https://www.googleapis.com/auth/script.scriptapp
Ermöglicht es, im Projekt Trigger zu erstellen. |
Vorschau von Drittanbieter-Links |
https://www.googleapis.com/auth/workspace.linkpreview
Erforderlich, wenn das Add-on Links von einem Drittanbieterdienst in der Vorschau anzeigt. Ermöglicht es dem Projekt, einen Link in einer Google Workspace-Anwendung zu sehen, während der Nutzer damit interagiert. Weitere Informationen finden Sie unter Vorschaulinks mit Smartchips erstellen. |
Ressourcen von Drittanbietern erstellen |
https://www.googleapis.com/auth/workspace.linkcreate
Erforderlich, wenn das Add-on Ressourcen in einem Drittanbieterdienst erstellt. Ermöglicht es dem Projekt, die Informationen zu lesen, die Nutzer im Formular zum Erstellen von Ressourcen einreichen, und einen Link zur Ressource in eine Google Workspace-Anwendung einzufügen. Weitere Informationen finden Sie unter Drittanbieterressourcen über das Dreipunkt-Menü erstellen. |