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-Benutzeroberfläche eine Autorisierungsaufforderung angezeigt, um den Autorisierungsvorgang zu starten.

Während dieses Vorgangs teilt die Eingabeaufforderung dem Nutzer mit, für welche Aktionen die App eine Berechtigung fordert. Beispielsweise könnte ein Add-on die Berechtigung anfordern, die E-Mail-Nachricht eines Nutzers zu lesen oder Termine in seinem Kalender zu erstellen. Diese Berechtigungen werden im Skriptprojekt des Add-ons 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 Bereichs an. Beispielsweise kann das Google Workspace-Add-on den Bereich „Aktuelle Nachricht lesen“ verwenden, der in Ihrem Manifest als https://www.googleapis.com/auth/gmail.addons.current.message.readonly angegeben ist. Während des Autorisierungsvorgangs wird der Nutzer von einem Add-on mit diesem Bereich aufgefordert, dem Add-on Folgendes zu erlauben: E-Mails abrufen, wenn das Add-on ausgeführt wird.

Bereiche ansehen

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

  1. Öffnen Sie das Skriptprojekt.
  2. Klicken Sie links auf Übersicht .
  3. 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, 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 erfordern. Bei den meisten Skripts ist dies ausreichend und spart Zeit. Bei veröffentlichten Add-ons sollten Sie jedoch die Bereiche direkter steuern.

Apps Script kann einem Add-on-Skriptprojekt beispielsweise standardmäßig den sehr weitreichenden 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 kleineren Satz ersetzen, der die Anforderungen des Add-ons und nicht mehr abdeckt.

Sie können die Bereiche, die Ihr Skriptprojekt verwendet, explizit festlegen, indem Sie die 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 das Add-on derzeit verwendet. Bestimmen Sie, welche Änderungen vorgenommen werden müssen, z. B. durch einen engeren Anwendungsbereich.
  2. Öffnen Sie die Manifestdatei des Add-ons.
  3. Suchen Sie das Feld der obersten Ebene mit der Bezeichnung oauthScopes. Ist er nicht vorhanden, können Sie ihn hinzufügen.
  4. Das Feld oauthScopes gibt ein Stringarray 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 zur Erweiterung von Gmail 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, 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 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 alle angegebenen Einschränkungen einhalten, bevor es veröffentlicht werden kann.

Prüfen Sie die vollständige Liste der eingeschränkten Bereiche, bevor Sie eine Veröffentlichung vornehmen. Wenn Ihr Add-on davon verwendet wird, 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 zu 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. Das Add-on kann auf nutzergenerierte Ereignisdaten zugreifen. 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. 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 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 das Add-on eine kontextbezogene Schnittstelle 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 ob das Add-on Zugriffsberechtigungen für 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. ä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 für die Anwendung zurücknimmt.

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

Gmail-Add-on-Bereiche

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 dem Add-on-Manifest diese und alle anderen Bereiche explizit hinzufügen, 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 Ihrem Google Workspace-Add-on-Manifest hinzugefügt werden, wenn Ihr Add-on Gmail erweitert.

Achten Sie außerdem darauf, den sehr breiten Bereich https://mail.google.com in Ihrem Add-on durch eine kleinere Gruppe von Bereichen zu ersetzen, die die Interaktionen ermöglichen, die Ihr Add-on benötigt, und nicht mehr.

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

Erforderlich, wenn das Add-on Trigger für Zusammensetzungsaktionen verwendet. Ermöglicht dem Add-on, vorübergehend neue Nachrichten- und Antwortentwürfe zu erstellen. Weitere Informationen finden Sie unter Nachrichtenentwürfe verfassen. Dieser Bereich wird auch häufig bei Nachrichtenentwürfen verwendet. Erfordert ein Zugriffstoken.

Metadaten offener Nachrichten 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. Betreff oder 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 Compose-Aktionen ist dieser Bereich erforderlich, wenn ein Zusammensetzungs-Trigger Zugriff auf Metadaten benötigt. In der Praxis lässt sich mit diesem Bereich eine E-Mail-Antwort auf Empfängerlisten (to:, cc: und bcc:) eines Antwort-E-Mail-Entwurfs erstellen.

Inhalt der geöffneten 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 des offenen Threads lesen https://www.googleapis.com/auth/gmail.addons.current.message.readonly

Gewährt temporären Zugriff auf die Metadaten und den Inhalt der geöffneten Nachricht. Gewährt außerdem Zugriff auf den Inhalt anderer Nachrichten im offenen Thread. Erfordert ein Zugriffstoken.

Nachrichteninhalt und -metadaten lesen https://www.googleapis.com/auth/gmail.readonly

Alle Metadaten und Inhalte von E-Mails 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.

Zugriffstokens

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

Im folgenden Beispiel wird gezeigt, wie Sie mit einem Zugriffstoken den Zugriff auf die Metadaten einer Nachricht zulassen. 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();
}

Bearbeiterbereiche

Im Folgenden finden Sie häufig verwendete Bereiche für Google Workspace-Add-ons, die Docs, Tabellen und 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 Apps Script Sheets API 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 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 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. ä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 für die Anwendung deaktiviert.

Andere Bereiche

Für Ihr Add-on sind möglicherweise zusätzliche Bereiche erforderlich, wenn es andere 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 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 Bibliothek OAuth2 für Apps Script verwendet.

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

Ermöglicht dem Projekt, die Sprache und 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 ansehen 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-App zu sehen, während der Nutzer damit interagiert. Weitere Informationen finden Sie unter Vorschaulinks mit Smartchips.

Ressourcen von Drittanbietern 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 zur Ressourcenerstellung einreichen, und einen Link zur Ressource in einer Google Workspace-Anwendung einzufügen. Weitere Informationen finden Sie unter Ressourcen von Drittanbietern über das @-Menü erstellen.