Diese Seite wurde von der Cloud Translation API übersetzt.

Bereiche

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 wird dem Nutzer in der Aufforderung mitgeteilt, für welche Aktionen die App 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 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. Ihr Google Workspace-Add-on kann beispielsweise den Umfang „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 .
Sie finden die Bereiche unter „OAuth-Bereiche des Projekts“.

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

Explizite Bereiche festlegen

In Apps Script wird automatisch ermittelt, welche Bereiche ein Script benötigt. Dazu wird der Code nach Funktionsaufrufen gescannt, für die sie erforderlich sind. 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 in Ihrem Scriptprojekt verwendet werden, 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:

Hier sehen Sie die Bereiche, die Ihr Add-on derzeit verwendet. 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.
Im Feld oauthScopes wird ein Array von Strings angegeben. Wenn Sie die Bereiche festlegen möchten, die in Ihrem Projekt verwendet werden, ersetzen Sie den Inhalt dieses Arrays durch die gewünschten Bereiche. Für ein Google Workspace-Add-on, das Gmail erweitert, können Sie beispielsweise Folgendes angeben:
```
{
  ...
  "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:

Eingeschränkter Geltungsbereich

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, 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

In den folgenden Abschnitten finden Sie 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 Docs, Sheets und Präsentationen erweitern.

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

Umfang
Aktueller Zugriff auf Google Docs-Dateien	`https://www.googleapis.com/auth/documents.currentonly` Erforderlich, wenn das Add-on auf die Docs API von Apps Script 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.
Zugriff auf aktuelle Google Präsentationen-Datei	`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 `onFileScopeGrantedTrigger` verwenden kann und das Add-on auf die Docs-, Sheets-, Präsentationen- oder Drive API zugreift. Gewährt pro Datei Zugriff auf Dateien, die von der App erstellt oder geöffnet wurden, mithilfe des erweiterten Drive-Dienstes von Apps Script. Ähnliche Aktionen mit dem grundlegenden Drive-Dienst sind jedoch nicht möglich. Die Dateiautorisierung wird pro Datei gewährt und widerrufen, wenn der Nutzer die Autorisierung der App aufhebt.

Gmail

Es gibt einige Bereiche, die speziell für Google Workspace-Add-ons entwickelt wurden, um die Gmail-Daten der Nutzer zu schützen. Sie müssen diese Bereiche explizit in das Add-on-Manifest einfügen, zusammen mit allen anderen Bereichen, 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 Vorschläge 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 Entwurfsnachrichten verfassen. Dieser Umfang wird auch häufig mit Aktionen zum Verfassen verwendet. Erfordert ein Zugriffstoken.
Metadaten der geöffneten Nachricht lesen	`https://www.googleapis.com/auth/gmail.addons.current.message.metadata` Gewährt vorübergehenden Zugriff auf die Metadaten der geöffneten Nachricht, z. B. 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 kann mit diesem Umfang ein Trigger für den Zugriff auf Empfängerlisten („An:“, „Cc:“ und „Bcc:“) eines E-Mail-Entwurfs für eine Antwort ausgelöst werden.
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 nach 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. Warnung: Dies ist ein sehr breiter, eingeschränkter Bereich. Verwenden Sie sie nur, wenn es unbedingt notwendig ist.

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 Kalenderereignismetadaten zugreift. Ermöglicht dem Add-on den Zugriff auf Ereignismetadaten.
Von Nutzern generierte 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 `addOns.calendar.eventAccess`-Manifest-Feld auf `READ` oder `READ_WRITE` gesetzt ist.
Nutzergenerierte Ereignisdaten schreiben	`https://www.googleapis.com/auth/calendar.addons.current.event.write` Erforderlich, wenn das Add-on von Nutzern generierte Ereignisdaten schreiben muss. Ermöglicht dem Add-on, von Nutzern generierte Ereignisdaten zu bearbeiten. Diese Daten sind nur verfügbar, wenn das `addOns.calendar.eventAccess`-Manifest-Feld auf `WRITE` oder `READ_WRITE` gesetzt ist.

Google Chat-Bereiche

Wenn Sie die Chat API aufrufen möchten, müssen Sie sich als Google Chat-Nutzer oder als Chat-App authentifizieren. Für jede Art der Authentifizierung sind unterschiedliche Bereiche erforderlich. Nicht alle Chat API-Methoden unterstützen die App-Authentifizierung.

Weitere Informationen zu Chat-Bereichen und Authentifizierungstypen finden Sie in der Übersicht über Authentifizierung und Autorisierung der Chat API.

In der folgenden Tabelle sind häufig verwendete Chat API-Methoden und ‑Bereiche basierend auf den unterstützten Authentifizierungstypen aufgeführt:

Methode	App-Authentifizierung wird unterstützt	Unterstützte Autorisierungsbereiche
Nachricht senden		Bei der Nutzerauthentifizierung: `chat.messages.create` `chat.messages` `chat.import` Mit App-Authentifizierung: `chat.bot`
Gruppenbereich erstellen		Bei der Nutzerauthentifizierung: `chat.spaces.create` `chat.spaces` `chat.import` Mit App-Authentifizierung und Administratorgenehmigung (verfügbar in der Entwicklervorschau): `chat.app.spaces.create` `chat.app.spaces`
Gruppenbereiche erstellen und Mitglieder hinzufügen	–	Bei der Nutzerauthentifizierung: `chat.spaces.create` `chat.spaces`
Nutzer zu einem Gruppenbereich hinzufügen		Bei der Nutzerauthentifizierung: `chat.memberships` `chat.memberships.app` `chat.import` Mit App-Authentifizierung und Administratorgenehmigung (verfügbar in der Entwicklervorschau): `chat.app.memberships`
Aktivitäten oder Ereignisse aus einem Chatbereich auflisten	–	Bei der Nutzerauthentifizierung müssen Sie für jeden Ereignistyp in der Anfrage einen Bereich angeben: Für Ereignisse zu Nachrichten: `chat.messages` `chat.messages.readonly` Für Ereignisse zu Reaktionen: `chat.messages.reactions` `chat.messages.reactions.readonly` `chat.messages` `chat.messages.readonly` Für Ereignisse zu Mitgliedschaften: `chat.memberships` `chat.memberships.readonly` Für Ereignisse im Gruppenbereich: `chat.spaces` `chat.spaces.readonly`

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

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 es 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, die Symbol-URL und die Berechtigung des Add-ons zum Zugriff auf das Element beschränkt.
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. Ähnliche Aktionen mit dem grundlegenden Drive-Dienst sind jedoch nicht möglich. Die Dateiautorisierung wird pro Datei gewährt und widerrufen, wenn der Nutzer die Autorisierung der App aufhebt. Weitere Informationen finden Sie im Beispiel Anfrage für den Dateizugriff für ausgewählte Dateien.

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 es 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, die Symbol-URL und die Berechtigung des Add-ons zum Zugriff auf das Element beschränkt.

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. Ähnliche Aktionen mit dem grundlegenden Drive-Dienst sind jedoch nicht möglich. Die Dateiautorisierung wird pro Datei gewährt und widerrufen, wenn der Nutzer die Autorisierung der App aufhebt.

Weitere Informationen finden Sie im Beispiel Anfrage für den Dateizugriff für ausgewählte Dateien.

Zugriffstokens

Zum Schutz von Nutzerdaten gewähren die Gmail-Bereiche, die in Google Workspace-Add-ons verwendet werden, nur vorübergehenden Zugriff auf Nutzerdaten. Wenn Sie den vorübergehenden Zugriff aktivieren möchten, müssen Sie die Funktion GmailApp.setCurrentMessageAccessToken(accessToken) mit einem Zugriffstoken als Argument aufrufen. Du musst ein Zugriffstoken von einem Ereignisobjekt vom Typ „Aktion“ abrufen.

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 es andere Google Workspace- oder Apps Script-Dienste verwendet. 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.

In der folgenden Tabelle sind die Bereiche aufgeführt, die in Google Workspace-Add-ons häufig 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, `UrlFetch`-Anfragen zu stellen. Dies ist auch erforderlich, wenn im Projekt die OAuth2 für Apps Script-Bibliothek verwendet wird.
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 für Links von Drittanbietern	`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 über das Formular zum Erstellen von Ressourcen senden, und einen Link zur Ressource in eine Google Workspace-Anwendung einzufügen. Weitere Informationen finden Sie unter Drittanbieterressourcen über das Dreipunkt-Menü erstellen.