Diese Seite wurde von der Cloud Translation API übersetzt.

Sucher

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-UI eine Autorisierungsaufforderung angezeigt, über die der Autorisierungsvorgang gestartet werden kann.

Während dieses Ablaufs teilt die Eingabeaufforderung dem Nutzer mit, für welche Berechtigung die Anwendung die Berechtigung benötigt. Ein Add-on kann beispielsweise die Berechtigung anfordern, 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.

Bereiche deklarieren Sie in Ihrem Manifest mithilfe von URL-Strings. Während des Autorisierungsvorgangs zeigt Apps Script dem Nutzer eine für Menschen lesbare Beschreibung des Umfangs an. 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 fordert ein Add-on mit diesem Bereich den Nutzer auf, dem Add-on folgende Berechtigungen zu erteilen: E-Mails ansehen, wenn das Add-on ausgeführt wird.

Bereiche ansehen

Sie können die Bereiche sehen, die Ihr Skriptprojekt derzeit benötigt. Gehen Sie dazu so vor:

Öffnen Sie das Skriptprojekt.
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 aufrufen, aber nur dann, wenn Sie diese Bereiche explizit festgelegt haben.

Explizite Bereiche festlegen

Apps Script ermittelt automatisch, welche Bereiche ein Skript benötigt, indem es den Code auf Funktionsaufrufe scannt, die diese erfordern. Bei den meisten Skripts ist dies ausreichend und spart Zeit. Bei veröffentlichten Add-ons sollten Sie jedoch die Bereiche direkter kontrollieren.

Beispielsweise kann Apps Script einem Add-on-Skriptprojekt standardmäßig den sehr eingeschränkten Bereich https://mail.google.com zuweisen. Wenn ein Nutzer ein Skriptprojekt mit diesem Bereich autorisiert, erhält das Projekt vollständigen Zugriff auf das Gmail-Konto des Nutzers. Bei veröffentlichten Add-ons müssen Sie diesen Bereich durch einen eingeschränkteren Bereich ersetzen, der 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:

Sehen Sie sich an, welche Bereiche das Add-on derzeit verwendet. Bestimmen Sie, welche Änderungen vorgenommen werden müssen, z. B. durch einen enger gefassten Anwendungsbereich.
Öffnen Sie die Manifestdatei des Add-ons.
Suchen Sie das oberste Feld mit der Bezeichnung oauthScopes. Ist er nicht vorhanden, können Sie ihn hinzufügen.
Das Feld oauthScopes gibt ein Array von Strings an. Um die von Ihrem Projekt verwendeten Bereiche festzulegen, ersetzen Sie den Inhalt dieses Arrays durch die Bereiche, die es verwenden soll. 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

Wenn Sie bestimmte vertrauliche OAuth-Bereiche verwenden, muss Ihr Add-on möglicherweise erst 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 zum Schutz von 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 vor der Veröffentlichung die vollständige Liste der eingeschränkten Bereiche an. 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.

Kalenderbereiche

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, auf Ereignismetadaten zuzugreifen.
Von Nutzern erstellte 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 von Nutzern erstellte Ereignisdaten. Diese Daten sind nur verfügbar, wenn das Manifestfeld `addOns.calendar.eventAccess` auf `READ` oder `READ_WRITE` gesetzt ist.
Von Nutzern erstellte Ereignisdaten schreiben	`https://www.googleapis.com/auth/calendar.addons.current.event.write` Erforderlich, wenn das Add-on von Nutzern erstellte Ereignisdaten schreiben muss. Das Add-on darf von Nutzern erstellte Ereignisdaten bearbeiten. Diese Daten sind nur verfügbar, wenn das Manifestfeld `addOns.calendar.eventAccess` auf `WRITE` oder `READ_WRITE` gesetzt ist.

Drive-Bereiche

Im Folgenden finden Sie häufig verwendete Bereiche für Google Workspace-Add-ons, die Google Drive erweitern.

Umfang

Ausgewählte Objektmetadaten lesen

Umfang
Ausgewählte Objektmetadaten lesen	`https://www.googleapis.com/auth/drive.addons.metadata.readonly` Erforderlich, wenn das Add-on eine kontextbezogene Oberflä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 beschränkt auf die ID, den Titel, den MIME-Typ und die Symbol-URL des Elements und darauf, ob das Add-on Zugriff auf das Element hat.
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 mit dem erweiterten Drive-Dienst von Apps Script erstellt oder geöffnet werden. Die Verwendung ähnlicher Aktionen im grundlegenden Drive-Dienst ist jedoch nicht erlaubt. Die Dateiautorisierung wird pro Datei gewährt und wird widerrufen, wenn der Nutzer die Autorisierung der App aufhebt. Weitere Informationen finden Sie unter 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 Oberflä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 beschränkt auf die ID, den Titel, den MIME-Typ und die Symbol-URL des Elements und darauf, ob das Add-on Zugriff auf das Element hat.

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 mit dem erweiterten Drive-Dienst von Apps Script erstellt oder geöffnet werden. Die Verwendung ähnlicher Aktionen im grundlegenden Drive-Dienst ist jedoch nicht erlaubt. Die Dateiautorisierung wird pro Datei gewährt und wird widerrufen, wenn der Nutzer die Autorisierung der App aufhebt.

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

Bereiche für Gmail-Add-ons

Es gibt einige Bereiche, die speziell für Google Workspace-Add-ons erstellt wurden, um die Gmail-Daten der Nutzer zu schützen. Sie müssen dem Add-on-Manifest diese Bereiche explizit hinzufügen, ebenso wie alle anderen, die der Add-on-Code erfordert.

Im Folgenden finden Sie häufig verwendete Bereiche für Google Workspace-Add-ons, die Gmail erweitern. Die mit Erforderlich gekennzeichneten Bereiche müssen Ihrem Google Workspace-Add-on-Manifest hinzugefügt werden, wenn Ihr Add-on Gmail erweitert.

Ersetzen Sie außerdem den sehr breiten Bereich https://mail.google.com in Ihrem Add-on durch einen kleineren Bereich, der die Interaktionen ermöglicht, die Ihr Add-on benötigt.

Umfang
Neue Entwürfe erstellen	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Erforderlich, wenn das Add-on Auslöser für die Erstellungsaktion verwendet. Das Add-on kann vorübergehend neue Entwürfe für Nachrichten und Antworten erstellen. Weitere Informationen finden Sie unter Nachrichtenentwürfe verfassen. Dieser Bereich wird auch häufig bei E-Mail-Nachrichtenentwürfen 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 Erstellungsaktionen verwendet. Für E-Mail-Schreiben ist dieser Bereich erforderlich, wenn ein Erstellungsauslöser Zugriff auf Metadaten benötigt. In der Praxis ermöglicht dieser Bereich einen Compose-Trigger, um auf Empfängerlisten (to:, cc: und bcc:) eines Antwort-E-Mail-Entwurfs zuzugreifen.
Geöffnete Nachricht lesen	`https://www.googleapis.com/auth/gmail.addons.current.message.action` Gewährt Zugriff auf den Inhalt der geöffneten Nachricht, wenn eine Nutzerinteraktion erfolgt, z. B. wenn ein Add-on-Menüelement ausgewählt wird. Erfordert ein Zugriffstoken.
Inhalt offener 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. Außerdem wird Zugriff auf den Inhalt anderer Nachrichten im offenen Thread gewährt. Erfordert ein Zugriffstoken.
Nachrichteninhalte und -metadaten lesen	`https://www.googleapis.com/auth/gmail.readonly` Alle E-Mail-Metadaten und -Inhalte lesen, einschließlich der geöffneten Nachricht. Erforderlich, wenn Sie Informationen zu anderen Nachrichten lesen müssen, z. B. beim Durchführen einer Suchanfrage oder beim Lesen eines gesamten E-Mail-Threads. Warnung: Dies ist ein sehr großer, eingeschränkter Bereich. Verwenden Sie es nur, wenn es unbedingt erforderlich ist.

Zugriffstokens

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

Das folgende Beispiel zeigt, wie ein Zugriffstoken festgelegt wird, 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();
}

Editor-Bereiche

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 Dateizugriff für 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 den Inhalt der geöffneten Tabelle.
Aktueller Dateizugriff in Google Präsentationen	`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 den Inhalt der geöffneten Präsentation.
Zugriff pro Datei	`https://www.googleapis.com/auth/drive.file` Erforderlich, damit das Add-on `onFileScopeGrantedTrigger` verwenden kann und wenn das Add-on auf die Docs, Tabellen, Präsentationen oder Drive API zugreift. Gewährt pro Datei Zugriff auf Dateien, die von der App mit dem erweiterten Drive-Dienst von Apps Script erstellt oder geöffnet werden. Die Verwendung ähnlicher Aktionen im grundlegenden Drive-Dienst ist jedoch nicht erlaubt. Die Dateiautorisierung wird für jede einzelne Datei gewährt und widerrufen, wenn der Nutzer die Autorisierung für die App aufhebt.

Andere Bereiche

Ihr Add-on benötigt möglicherweise zusätzliche Bereiche, wenn es andere Apps Script-Dienste verwendet. In den meisten Fällen können Sie Apps Script diese Bereiche erkennen lassen und das Manifest automatisch aktualisieren. Entfernen Sie beim Bearbeiten der Bereichsliste des Manifests keine Bereiche, es sei denn, Sie ersetzen sie durch eine geeignetere Alternative, z. B. einen engeren Bereich.

Hier finden Sie eine Liste von Apps Script-Bereichen, die häufig in Verbindung mit 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 senden. Dies ist auch erforderlich, wenn das Projekt die OAuth2-Bibliothek für Apps Script verwendet.
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 lernen. Weitere Informationen finden Sie unter Auf das Gebietsschema und die Zeitzone des Nutzers zugreifen.
Trigger erstellen	`https://www.googleapis.com/auth/script.scriptapp` Ermöglicht dem Projekt, Trigger zu erstellen.
Vorschau von Drittanbieter-Links anzeigen	`https://www.googleapis.com/auth/workspace.linkpreview` Erforderlich, wenn das Add-on Links eines Drittanbieterdienstes in der Vorschau anzeigt. Ermöglicht dem Projekt, einen Link in einer Google Workspace-App aufzurufen, während der Nutzer damit interagiert. Weitere Informationen findest du unter Vorschaulinks mit Smartchips.
Ressourcen von Drittanbietern erstellen	`https://www.googleapis.com/auth/workspace.linkcreate` Entwicklervorschau:Diese Funktion ist im Rahmen des Google Workspace-Entwicklerprogramms für Entwickler verfügbar, das Vorabzugriff auf bestimmte Funktionen gewährt. Erforderlich, wenn das Add-on Ressourcen in einem Drittanbieterdienst erstellt. Ermöglicht dem Projekt, die Informationen zu lesen, die Nutzer über das Formular zur Ressourcenerstellung senden, und einen Link zur Ressource in einer Google Workspace-Anwendung einzufügen. Weitere Informationen finden Sie unter Drittanbieterressourcen über das @-Menü erstellen.