Sucher

Nutzer müssen Add-ons und andere Anwendungen autorisieren, die auf ihre Daten zugreifen oder in deren Namen handeln. Wenn ein Nutzer ein Add-on zum ersten Mal ausführt, wird in der Add-on-UI eine Autorisierungsaufforderung angezeigt, mit der der Autorisierungsvorgang gestartet werden kann.

Während dieses Vorgangs wird der Nutzer über die Aufforderung aufgefordert, die gewünschte Aktion auszuführen. Zum Beispiel benötigt ein Add-on die Berechtigung, die E-Mail-Nachricht eines Nutzers zu lesen oder in seinem Kalender Termine zu erstellen. Das Skriptprojekt des Add-ons definiert diese einzelnen Berechtigungen als OAuth-Bereiche.

Sie deklarieren Bereiche in Ihrem Manifest mit URL-Strings. Während des Autorisierungsvorgangs zeigt Apps Script dem Nutzer eine für Menschen lesbare Beschreibung des Bereichs an. Ihr 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 Bereich dazu aufgefordert, dem Add-on folgende Berechtigung zu gewähren: E-Mails abrufen, wenn das Add-on ausgeführt wird.

Anzeigebereiche

So sehen Sie die Bereiche, die Ihr Skriptprojekt derzeit benötigt:

Neuer Editor

  1. Öffnen Sie das Skriptprojekt.
  2. Klicken Sie links auf Übersicht .
  3. Rufen Sie die Bereiche unter & Projekt-OAuth-Bereiche auf.

Alter Editor

  1. Öffnen Sie das Skriptprojekt im Apps Script-Editor.
  2. Wählen Sie im Menü Datei > Projekteigenschaften aus.
  3. Wählen Sie den Tab Scopes (Bereiche) aus.

Bereiche werden unten im Fenster unter der Überschrift Projekt-OAuth-Bereiche aufgelistet.

Sie können die aktuellen Bereiche des Skriptprojekts auch im Projektmanifest im Feld oauthScopes aufrufen, wenn Sie diese Bereiche explizit festgelegt haben.

Explizite Bereiche festlegen

Apps Script ermittelt automatisch den Umfang eines Skripts, indem dessen Code auf Funktionsaufrufe geprüft wird, für die sie erforderlich sind. Bei den meisten Skripts ist das ausreichend und spart Zeit, aber bei veröffentlichten Add-ons sollten Sie die Bereiche direkter steuern.

Beispielsweise kann Apps Script ein Add-on-Skriptprojekt standardmäßig mit dem sehr moderaten Bereich https://mail.google.com versehen. 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 begrenzten Satz von Add-ons ersetzen, die die Anforderungen des Add-ons abdecken.

Sie können die von Ihrem Skriptprojekt verwendeten Bereiche explizit festlegen, indem Sie die zugehörige Manifestdatei bearbeiten. Das Manifestfeld oauthScopes ist ein Array aller Bereiche, die vom Add-on verwendet werden. So legen Sie die Bereiche Ihres Projekts fest:

  1. Sehen Sie sich an, welche Bereiche derzeit von Ihrem Add-on verwendet werden. Ermitteln Sie, welche Änderungen erforderlich sind, z. B. mit einem enger gefassten Bereich.
  2. Öffnen Sie die Manifestdatei Ihres Add-ons.
  3. Suchen Sie das oberste Feld mit dem Namen oauthScopes. Wenn sie nicht vorhanden ist, können Sie sie hinzufügen.
  4. Im Feld oauthScopes wird ein String-Array angegeben. Wenn Sie die von Ihrem Projekt verwendeten Bereiche festlegen möchten, ersetzen Sie den Inhalt dieses Arrays durch die gewünschten Bereiche. 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"
      ],
      ...
    }
    
  5. Speichern Sie die Änderungen an der Manifestdatei.

OAuth-Überprüfung

Wenn Sie bestimmte vertrauliche OAuth-Bereiche verwenden möchten, muss Ihr Add-on möglicherweise die OAuth-Clientbestätigung 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, um Nutzerdaten zu schützen. Wenn Sie ein Gmail- oder Editor-Add-on mit einem oder mehreren eingeschränkten Bereichen veröffentlichen möchten, muss das Add-on alle angegebenen Einschränkungen einhalten, bevor es veröffentlicht werden kann.

Prüfen Sie die vollständige Liste der eingeschränkten Bereiche, bevor Sie versuchen, sie zu veröffentlichen. Wenn Ihr Add-on einen davon 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 Kalender-Terminmetadaten zugreift. Das Add-on kann auf Ereignismetadaten zugreifen.

Von Nutzern erstellte Ereignisdaten lesen https://www.googleapis.com/auth/calendar.addons.current.event.read

Erforderlich, wenn das Add-on vom Nutzer erstellte Ereignisdaten lesen muss. Das Add-on hat Zugriff auf von Nutzern erstellte Ereignisdaten. Diese Daten sind nur verfügbar, wenn das Manifestfeld addOns.calendar.eventAccess auf READ oder READ_WRITE festgelegt ist.

Von Nutzern erstellte Ereignisdaten schreiben https://www.googleapis.com/auth/calendar.addons.current.event.write

Erforderlich, wenn das Add-on nutzergenerierte Ereignisdaten schreiben muss. Das Add-on darf vom Nutzer erstellte Ereignisdaten bearbeiten. Diese Daten sind nur verfügbar, wenn das Manifestfeld addOns.calendar.eventAccess auf WRITE oder READ_WRITE festgelegt ist.

Drive-Bereiche

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

Umfang
Ausgewählte Elementmetadaten lesen https://www.googleapis.com/auth/drive.addons.metadata.readonly

Erforderlich, wenn mit dem Add-on eine Kontextoberfläche implementiert wird, die ausgelöst wird, wenn der Nutzer Elemente in Drive auswählt. Das Add-on kann eingeschränkte Metadaten zu Elementen lesen, die ein Nutzer in Google Drive ausgewählt hat. Die Metadaten sind auf die ID, den Titel, den MIME-Typ, die Symbol-URL des Elements und darauf beschränkt, ob das Add-on berechtigt ist, auf das Element zuzugreifen.

Zugriff pro Datei https://www.googleapis.com/auth/drive.file

Empfohlen, wenn das Add-on auf einzelne Drive-Dateien zugreifen muss. Gewährt pro Dateizugriff Zugriff auf Dateien, die von der Anwendung mit dem erweiterten Drive-Dienst von Apps Script erstellt oder geöffnet wurden. Die Verwendung ähnlicher Aktionen mit dem einfachen Drive-Dienst ist jedoch nicht möglich. Die Dateiautorisierung wird pro Datei erteilt und widerrufen, wenn der Nutzer die Anwendung deaktiviert.

Weitere Informationen finden Sie im Beispiel für den Zugriff auf Dateien für ausgewählte Dateien.

Gmail-Add-on-Bereiche

Es gibt einige Bereiche, die speziell für Google Workspace-Add-ons zum Schutz der Gmail-Daten von Nutzern erstellt wurden. Sie müssen Ihrem Add-on-Manifest genau diese Bereiche hinzufügen, zusammen mit allen anderen, die Ihr Add-on-Code benötigt.

Nachfolgend finden Sie häufig verwendete Bereiche für Google Workspace-Add-ons, die Gmail erweitern. Sie müssen dem Google Workspace-Add-on-Manifest als Erforderlich hinzugefügt werden, wenn es Gmail erweitert.

Ersetzen Sie unbedingt den sehr breiten https://mail.google.com-Bereich in Ihrem Add-on durch einen enger gefassten Bereich, der die von Ihrem Add-on benötigten Interaktionen nicht mehr zulässt.

Umfang
Neue Entwürfe erstellen https://www.googleapis.com/auth/gmail.addons.current.action.compose

Erforderlich, wenn das Add-on Trigger für Aktionen zum Schreiben verwendet. Das Add-on darf vorübergehend neue Nachrichtenentwürfe und -antworten erstellen. Weitere Informationen finden Sie unter E-Mail-Entwürfe erstellen. Dieser Bereich wird häufig auch beim Schreiben von Aktionen 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 offenen Metadaten der Nachricht, z. B. auf den Betreff oder die Empfänger. Der Nachrichteninhalt darf nicht gelesen werden und es ist ein Zugriffstoken erforderlich.

Erforderlich, wenn das Add-on Metadaten in Triggern zum Schreiben von Aktionen verwendet. Für Schreiben ist dieser Bereich erforderlich, wenn ein Erstellungstrigger Zugriff auf Metadaten benötigt. In der Praxis können Sie mit diesem Bereich Empfängerlisten für den Zugriff auf Nachrichten (an:, cc: und bcc:) eines Antwort-E-Mail-Entwurfs auslösen.

Inhalt der geöffneten Nachricht lesen https://www.googleapis.com/auth/gmail.addons.current.message.action

Gewährt Zugriff auf die geöffnete Nachricht bei einer Nutzerinteraktion, z. B. wenn ein Add-on-Menüelement ausgewählt wird. Erfordert ein Zugriffstoken.

Geöffneten Thread-Inhalt lesen https://www.googleapis.com/auth/gmail.addons.current.message.readonly

Gewährt vorübergehend Zugriff auf die Metadaten und Inhalte der geöffneten Nachricht. Gewährt auch Zugriff auf den Inhalt anderer Nachrichten im offenen Thread. Erfordert ein Zugriffstoken.

Nachrichteninhalte und Metadaten lesen https://www.googleapis.com/auth/gmail.readonly

Lesen Sie alle E-Mail-Metadaten und -Inhalte, einschließlich der geöffneten Nachricht. Erforderlich, wenn Sie Informationen zu anderen Nachrichten lesen möchten, z. B. beim Ausführen einer Suchanfrage oder beim Lesen eines gesamten E-Mail-Threads.

Zugriffstokens

Zum Schutz von Nutzerdaten gewähren die in Google Workspace-Add-ons verwendeten Gmail-Bereiche nur temporären Zugriff auf Nutzerdaten. Zum Aktivieren des temporären Zugriffs müssen Sie die Funktion GmailApp.setCurrentMessageAccessToken(accessToken) aufrufen und dabei ein Zugriffstoken als Argument verwenden. Sie müssen ein Zugriffstoken von einem Aktionsereignisobjekt abrufen.

Das folgende Beispiel zeigt ein Zugriffstoken, das den Zugriff auf die Metadaten einer Nachricht zulässt. 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 Google Docs-Dateizugriff 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 den Inhalt des geöffneten Dokuments.

Zugriff auf aktuelle Google Tabellen-Datei 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.

Zugriff auf 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 den Inhalt der offenen Präsentation.

Zugriff pro Datei https://www.googleapis.com/auth/drive.file

Erforderlich, damit das Add-on die onFileScopeGrantedTrigger verwendet und auf die Docs, Tabellen, Präsentationen oder Drive REST APIs zugreift. Gewährt pro Dateizugriff Zugriff auf Dateien, die von der Anwendung mit dem erweiterten Drive-Dienst von Apps Script erstellt oder geöffnet wurden. Die Verwendung ähnlicher Aktionen mit dem einfachen Drive-Dienst ist jedoch nicht möglich. Die Dateiautorisierung wird pro Datei erteilt und widerrufen, wenn der Nutzer die Anwendung deaktiviert.

Andere Bereiche

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

Hier finden Sie eine Liste der Apps Script-Bereiche, 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 Bibliothek OAuth2 für Apps Script verwendet.

Sprache und Zeitzone des Nutzers lesen https://www.googleapis.com/auth/script.locale

Ermöglicht es dem Projekt, das Gebietsschema und die Zeitzone des aktuellen Nutzers kennenzulernen. Weitere Informationen findest du unter Auf Nutzersprache und Zeitzone zugreifen.

Trigger erstellen https://www.googleapis.com/auth/script.scriptapp

Ermöglicht dem Projekt, Trigger zu erstellen.