Diese Seite wurde von der Cloud Translation API übersetzt.

Bereiche

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 Google Workspace-Add-on verwendet beispielsweise den Bereich „Aktuelle Nachricht lesen“, der in Ihrem Manifest als https://www.googleapis.com/auth/gmail.addons.current.message.readonly angegeben ist. Während des Autorisierungsvorgangs wird der Nutzer bei einem Add-on mit diesem Bereich aufgefordert, dem Add-on zu erlauben, E‑Mails abzurufen, wenn das Add-on ausgeführt wird.

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 „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.

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 derzeit verwendet werden Legen Sie fest, welche Änderungen vorgenommen werden müssen, z. B. die Verwendung eines engeren Bereichs.
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 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 Google Workspace-Add‑on, das Gmail erweitert, könnten Sie beispielsweise Folgendes haben:
```
{
  ...
  "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

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:

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.

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 Google Workspace-Add‑ons auswählen

In den folgenden Abschnitten finden Sie Bereiche, die häufig für Google Workspace-Add-ons verwendet werden.

Editor-Bereiche

Unten finden Sie häufig verwendete Bereiche für Google Workspace-Add-ons, die Google Docs, Google Sheets und Google Präsentationen erweitern.

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.

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 temporären Zugriff auf die Inhalte des geöffneten Dokuments.
Zugriff auf aktuelle Google-Tabellen	`https://www.googleapis.com/auth/spreadsheets.currentonly` Erforderlich, wenn das Add-on auf die Apps Script Sheets API zugreift. Gewährt vorübergehenden Zugriff auf die Inhalte der geöffneten Tabelle.
Zugriff auf die aktuelle Präsentationen-Datei	`https://www.googleapis.com/auth/presentations.currentonly` Erforderlich, wenn das Add-on auf die Apps Script Slides 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 wenn das Add-on auf die Docs-, Sheets-, Präsentationen- oder Drive-API zugreift. Gewährt Zugriff auf Dateien, die von der App erstellt oder geöffnet wurden, mithilfe des erweiterten Drive-Dienstes von Apps Script. Dies erlaubt jedoch nicht die Verwendung ähnlicher Aktionen mit dem einfachen Drive-Dienst. Die Dateiautorisierung wird pro Datei erteilt und widerrufen, wenn der Nutzer die Autorisierung der App aufhebt.

Gmail

Es gibt einige Bereiche, die speziell für Google Workspace-Add-ons erstellt wurden, um die Gmail-Daten von Nutzern zu schützen. Sie müssen diese Bereiche explizit in das Add-on-Manifest aufnehmen, zusammen mit allen anderen, die für den Add-on-Code erforderlich sind.

Nachfolgend 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 allgemeinen Bereich https://mail.google.com in Ihrem Add-on durch eine engere Gruppe von Bereichen, die nur die Interaktionen ermöglichen, 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 Compose-Aktionstrigger verwendet. Ermöglicht dem Add-on, vorübergehend neue Nachrichtenentwürfe und Antworten zu erstellen. Weitere Informationen finden Sie unter Nachrichtentwürfe erstellen. Dieser Bereich wird auch häufig mit Compose-Aktionen verwendet. Ein Zugriffstoken ist erforderlich.
Metadaten geöffneter Nachrichten 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. Betreff oder Empfänger. Das Lesen von Nachrichteninhalten ist nicht möglich und ein Zugriffstoken ist erforderlich. Erforderlich, wenn das Add-on Metadaten in Triggern für die Compose-Aktion verwendet. Für Compose-Aktionen ist dieser Bereich erforderlich, wenn ein Compose-Trigger Zugriff auf Metadaten benötigt. In der Praxis ermöglicht dieser Bereich einem Compose-Trigger den Zugriff auf Empfängerlisten („An:“, „Cc:“ und „Bcc:“) eines Antwort-E‑Mail-Entwurfs.
Inhalte offener 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 Add-on-Menüpunkt ausgewählt wird. Erfordert ein Zugriffstoken.
Inhalte offener Threads lesen	`https://www.googleapis.com/auth/gmail.addons.current.message.readonly` Gewährt temporären Zugriff auf die Metadaten und Inhalte der offenen Nachricht. Gewährt auch Zugriff auf den Inhalt anderer Nachrichten im geöffneten Thread. Ein Zugriffstoken ist erforderlich.
Nachrichteninhalte und Metadaten lesen	`https://www.googleapis.com/auth/gmail.readonly` E-Mail-Metadaten und -Inhalte lesen, einschließlich der geöffneten Nachricht. Erforderlich, wenn Sie Informationen zu anderen Nachrichten lesen müssen, z. B. wenn Sie eine Suchanfrage ausführen oder einen gesamten E‑Mail-Verlauf lesen. Warnung: Dies ist ein sehr allgemeiner eingeschränkter Bereich. Verwenden Sie sie nur, wenn es unbedingt erforderlich ist.

Google Kalender-Bereiche

Nachfolgend 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.
Nutzergenerierte Ereignisdaten lesen	`https://www.googleapis.com/auth/calendar.addons.current.event.read` Erforderlich, wenn das Add-on nutzergenerierte Ereignisdaten lesen muss. Ermöglicht dem Add-on den Zugriff auf nutzergenerierte Ereignisdaten. Diese Daten sind nur verfügbar, wenn das Manifestfeld `addOns.calendar.eventAccess` 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, nutzergenerierte Ereignisdaten zu bearbeiten. Diese Daten sind nur verfügbar, wenn das Manifestfeld `addOns.calendar.eventAccess` 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 die einzelnen Authentifizierungstypen sind unterschiedliche Bereiche erforderlich. Außerdem unterstützen nicht alle Chat API-Methoden die App-Authentifizierung.

Weitere Informationen zu Chat-Bereichen und Authentifizierungstypen finden Sie in der Übersicht zur 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		Mit Nutzerauthentifizierung: `chat.messages.create` `chat.messages` `chat.import` Mit der App-Authentifizierung: `chat.bot`
Gruppenbereich erstellen		Mit Nutzerauthentifizierung: `chat.spaces.create` `chat.spaces` `chat.import` Mit der App-Authentifizierung und der Administratorgenehmigung (verfügbar in der Entwicklervorschau): `chat.app.spaces.create` `chat.app.spaces`
Gruppenbereiche erstellen und Mitglieder hinzufügen	–	Mit Nutzerauthentifizierung: `chat.spaces.create` `chat.spaces`
Nutzer einem Gruppenbereich hinzufügen		Mit Nutzerauthentifizierung: `chat.memberships` `chat.memberships.app` `chat.import` Mit der App-Authentifizierung und der 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 verwenden: 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 im Zusammenhang mit Mitgliedschaften: `chat.memberships` `chat.memberships.readonly` Für Ereignisse zum 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 Elements lesen

Umfang
Metadaten des ausgewählten Elements 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, die Symbol-URL und die Berechtigung des Add-ons für den 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 Zugriff auf Dateien, die von der App erstellt oder geöffnet wurden, mithilfe des erweiterten Drive-Dienstes von Apps Script. Dies erlaubt jedoch nicht die Verwendung ähnlicher Aktionen mit dem einfachen Drive-Dienst. Die Autorisierung für Dateien wird pro Datei erteilt und widerrufen, wenn der Nutzer die Autorisierung der App aufhebt. Weitere Informationen finden Sie im Beispiel für das Anfordern des Dateizugriffs 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 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 für den 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 Zugriff auf Dateien, die von der App erstellt oder geöffnet wurden, mithilfe des erweiterten Drive-Dienstes von Apps Script. Dies erlaubt jedoch nicht die Verwendung ähnlicher Aktionen mit dem einfachen Drive-Dienst. Die Autorisierung für Dateien wird pro Datei erteilt und widerrufen, wenn der Nutzer die Autorisierung der App aufhebt.

Weitere Informationen finden Sie im Beispiel für das Anfordern des Dateizugriffs für ausgewählte Dateien.

Zugriffstokens

Zum Schutz von Nutzerdaten gewähren die in Google Workspace-Add-ons verwendeten Gmail-Bereiche nur vorübergehenden Zugriff auf Nutzerdaten. Um temporären Zugriff zu gewähren, müssen Sie die Funktion GmailApp.setCurrentMessageAccessToken(accessToken) mit einem Zugriffstoken als Argument aufrufen. Sie müssen ein Zugriffstoken von einem Aktionsereignisobjekt abrufen.

Das Folgende ist ein Beispiel für das Festlegen eines Zugriffstokens, um den Zugriff auf die Metadaten einer Nachricht zu ermöglichen. Der einzige für dieses Beispiel erforderliche Bereich ist https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

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 diese Bereiche von Apps Script erkennen und das Manifest automatisch aktualisieren lassen. Wenn Sie die Bereichsliste Ihres Manifests bearbeiten, entfernen Sie keine Bereiche, es sei denn, Sie ersetzen sie durch eine geeignetere Alternative, z. B. einen engeren Bereich.

In der folgenden Tabelle finden Sie 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, `UrlFetch`-Anfragen zu stellen. Dies ist auch erforderlich, wenn im Projekt die Bibliothek OAuth 2.0 für Apps Script verwendet wird.
Sprache und Zeitzone des Nutzers lesen	`https://www.googleapis.com/auth/script.locale` Ermöglicht dem Projekt, das Gebietsschema und die Zeitzone des aktuellen Nutzers zu ermitteln. Weitere Informationen finden Sie unter Auf Nutzer-Locale und ‑Zeitzone zugreifen.
Trigger erstellen	`https://www.googleapis.com/auth/script.scriptapp` Ermöglicht dem 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 dem Projekt, einen Link in einer Google Workspace-Anwendung zu sehen, während der Nutzer mit ihm interagiert. Weitere Informationen
Drittanbieterressourcen erstellen	`https://www.googleapis.com/auth/workspace.linkcreate` Erforderlich, wenn das Add-on Ressourcen in einem Drittanbieterdienst erstellt. Ermöglicht dem Projekt, die Informationen zu lesen, die Nutzer im Formular zum Erstellen von Ressourcen eingeben, und einen Link zur Ressource in eine Google Workspace-Anwendung einzufügen. Weitere Informationen