Bereiche

Nutzer müssen Add-ons und andere Anwendungen autorisieren, die auf ihre Daten zugreifen oder in dessen Namen handeln. Wenn ein Nutzer ein Add-on zum ersten Mal ausführt, Add-on-UI zeigt eine Autorisierungsaufforderung an, um den Autorisierungsvorgang zu starten.

Während dieses Vorgangs teilt die Eingabeaufforderung dem Nutzer mit, was die Anwendung möchte zu erteilen. Beispiel: Ein Add-on benötigt die Berechtigung zum Lesen eines E-Mail-Nachricht eines Nutzers senden oder Termine in seinem Kalender erstellen. Skript des Add-ons diese einzelnen Berechtigungen als OAuth-Bereiche definiert.

Sie deklarieren Bereiche in Ihrem Manifest mithilfe von URL-Strings. Während des Autorisierungsvorgangs zeigt Apps Script eine menschenlesbare Beschreibung des Umfangs. Beispiel: Ihr Google Workspace-Add-on die Option „Aktuelle Nachricht lesen“ Gültigkeitsbereich, der in Ihrem Manifest als https://www.googleapis.com/auth/gmail.addons.current.message.readonly Währenddessen wird der Nutzer von einem Add-on mit diesem Geltungsbereich aufgefordert, Add-on: E-Mails abrufen, wenn das Add-on ausgeführt wird

Bereiche anzeigen

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

  1. Öffnen Sie das Skriptprojekt.
  2. Klicken Sie links auf Übersicht.
  3. Sehen Sie sich die Bereiche unter „OAuth-Bereiche des Projekts“ an.

Die aktuellen Bereiche des Skriptprojekts finden Sie auch im Projektmanifest. im Rahmen der oauthScopes aber nur, wenn Sie diese Bereiche explizit festgelegt haben.

Explizite Bereiche festlegen

Apps Script erkennt automatisch, welche Bereiche ein Script benötigt, indem es gescannt wird seinen Code für Funktionsaufrufe, die diese erfordern. Bei den meisten Skripts ist dies ausreichend ist und Ihnen Zeit spart. Für veröffentlichte Add-ons sollten Sie jedoch den Umfang direkter zu steuern.

So kann Apps Script einem Add-on-Skriptprojekt beispielsweise Bereich https://mail.google.com. Wenn ein Nutzer ein Script autorisiert Projekt dieses Umfangs hat, wird dem Projekt uneingeschränkter Zugriff auf das Gmail-Konto des Nutzers gewährt, Konto. Bei veröffentlichten Add-ons müssen Sie diesen Bereich durch einen die die Anforderungen der Add-ons abdeckt.

Sie können die Bereiche, die Ihr Skriptprojekt verwendet, explizit festlegen, indem Sie die zugehörige Manifestdatei. Das Feld „manifest“ oauthScopes ist ein Array. aller vom Add-on verwendeten Bereiche. Um die Bereiche Ihres Projekts festzulegen, führen Sie die Folgendes:

  1. Aktuell vom Add-on verwendete Bereiche ansehen Bestimmen Sie, was müssen Änderungen vorgenommen werden, z. B. die Verwendung eines engeren Rahmens.
  2. Öffnen Sie die Manifestdatei des Add-ons.
  3. Suchen Sie das oberste Feld mit der Bezeichnung oauthScopes. Ist dies nicht der Fall, können Sie es hinzufügen.
  4. Die oauthScopes Feld gibt ein Array von Zeichenfolgen an. Bereiche festlegen die Ihr Projekt verwendet, ersetzen Sie den Inhalt dieses Arrays durch die Bereiche, verwenden möchten. Ein Google Workspace-Add-on zur Erweiterung von Gmail könnte beispielsweise Folgendes enthalten:

    {
      ...
      "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 OAuth-Clientbestätigung bevor Sie sie 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, Nutzerdaten zu schützen. Wenn Sie ein Gmail- oder Editor-Add-on veröffentlichen möchten, das einen oder mehrere eingeschränkte Bereiche haben, muss das Add-on allen Einschränkungen vor der Veröffentlichung.

Sehen Sie sich die vollständige Liste der eingeschränkten Bereiche an. bevor Sie die App veröffentlichen. Wenn in Ihrem Add-on eines davon verwendet wird, müssen Sie mit dem Zusätzliche Anforderungen für bestimmte API-Bereiche vor der Veröffentlichung.

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. Erlaubt um auf Ereignismetadaten zuzugreifen.

Von Nutzern erstellte 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 erstellte Ereignisdaten. Diese Daten sind nur verfügbar, wenn das <ph type="x-smartling-placeholder"></ph> addOns.calendar.eventAccess-Manifestfeld ist auf READ oder READ_WRITE festgelegt.

Nutzergenerierte 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, von Nutzern erstellte Ereignisdaten zu bearbeiten. Diese Daten sind nur verfügbar, wenn das <ph type="x-smartling-placeholder"></ph> addOns.calendar.eventAccess-Manifestfeld ist auf WRITE oder READ_WRITE festgelegt.

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 https://www.googleapis.com/auth/drive.addons.metadata.readonly

Erforderlich, wenn das Add-on eine Kontextschnittstelle implementiert, die ausgelöst wird Der Nutzer wählt Elemente in Drive aus. Ermöglicht dem Add-on, eingeschränkte Metadaten zu Objekten eines Nutzers zu lesen die Sie in Google Drive ausgewählt haben. Die Metadaten sind auf die ID des Artikels beschränkt, Titel, MIME-Typ, Symbol-URL und ob das Add-on die Berechtigung auf das Element zugreifen.

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

Empfohlen, wenn das Add-on auf einzelne Drive-Dateien zugreifen muss Dateien. Gewährt Zugriff pro Datei auf Dateien, die von der Anwendung erstellt oder geöffnet wurden unter Verwendung von Apps Script Erweitertes Drive Dienst. Die Verwendung ähnlicher Aktionen über das Google Drive-Basisdienst jedoch. Die Dateiautorisierung wird pro Datei gewährt und ist wird widerrufen, wenn der Nutzer die App deaktiviert.

Weitere Informationen finden Sie in der <ph type="x-smartling-placeholder"></ph> Beispiel für die Anforderung des Dateizugriffs auf ausgewählte Dateien

Gmail-Add-on-Bereiche

Einige Bereiche wurden speziell für Google Workspace-Add-ons zum Schutz von Gmail-Nutzern Daten. Du musst diese Bereiche explizit hinzufügen in Ihrem Add-on-Manifest und allen anderen, Add-on-Code benötigt wird.

Im Folgenden finden Sie häufig verwendete Bereiche für Google Workspace-Add-ons, die Gmail erweitern: müssen Sie die mit Erforderlich gekennzeichneten Einträge Ihrem Manifest für Google Workspace-Add-on, wenn das Add-on erweitert wird Gmail:

Ersetzen Sie auch den sehr breit gefassten https://mail.google.com-Bereich in Ihrem enger gefassten Gültigkeitsbereichen hinzu, die die Interaktionen und nicht mehr.

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

Erforderlich, wenn das Add-on <ph type="x-smartling-placeholder"></ph> Trigger zum Schreiben von Aktionen Dadurch kann das Add-on vorübergehend neue Entwürfe für Nachrichten und Antworten. Weitere Informationen finden Sie unter . Nachrichtenentwürfe verfassen . wird dieser Bereich häufig <ph type="x-smartling-placeholder"></ph> Schreibaktionen. 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 Metadaten der geöffneten Nachricht (z. B. Betreff oder Empfänger). Inhalt der Nachricht kann nicht gelesen werden und erfordert ein Zugriffstoken.

Erforderlich, wenn das Add-on beim Erstellen der Aktion Metadaten verwendet Trigger. Für Erstellen von Aktionen: Dieser Bereich ist erforderlich, wenn ein Trigger zum Schreiben Zugriff auf Metadaten benötigt. In der Praxis lässt sich mit diesem Bereich Empfängerlisten für den Zugriff (to:, cc: und bcc:) einer Antwort auslösen E-Mail-Entwurf.

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

Gewährt nach einer Nutzerinteraktion Zugriff auf den Inhalt der offenen Nachricht z. B. wenn ein Add-on-Menüpunkt ausgewählt wird. Zugriff erforderlich Token.

Inhalt des 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 offenen Modus Diskussions-Thread. Erfordert ein Zugriffstoken.

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

Alle Metadaten und Inhalte der E-Mail lesen, auch die geöffnete Nachricht. Erforderlich, wenn Sie Informationen zu anderen Nachrichten lesen müssen, z. B. wenn Sie eine Suchanfrage durchführen oder einen ganzen E-Mail-Thread lesen.

Zugriffstokens

Zum Schutz der Nutzerdaten werden die in Gewährung nur für Google Workspace-Add-ons vorübergehenden Zugriff auf Nutzerdaten. Um den temporären Zugriff zu ermöglichen, müssen Sie die Methode Funktion GmailApp.setCurrentMessageAccessToken(accessToken) mit einem Zugriffstoken als Argument. Sie erhalten ein Zugriffstoken von einer action-Ereignisobjekt.

Im Folgenden sehen Sie ein Beispiel für das Festlegen eines Zugriffstokens, um den Zugriff auf die Metadaten einer Nachricht. Der einzige Umfang, der für dieses Beispiel notwendig ist, 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.

Umfang
Aktueller Zugriff auf 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 offenen 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 offenen Präsentation.

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

Erforderlich, damit das Add-on onFileScopeGrantedTrigger verwenden kann und ob das Add-on auf die Docs, Tabellen, Präsentationen oder Drive API zugreift. Gewährt Zugriff pro Datei auf Dateien, die von der Anwendung erstellt oder geöffnet wurden unter Verwendung von Apps Script Erweitertes Drive Dienst. Die Verwendung ähnlicher Aktionen über das Google Drive-Basisdienst jedoch. Die Dateiautorisierung wird pro Datei gewährt und ist wenn der Nutzer die App deaktiviert.

Andere Umfänge

Wenn Ihr Add-on andere Apps Script-Dienste verwendet, sind möglicherweise zusätzliche Bereiche erforderlich. In den meisten Fällen können Sie zulassen, dass Apps Script diese Bereiche erkennt und den automatisch Manifest erstellen. Entfernen Sie beim Bearbeiten der Liste der Geltungsbereiche Ihres Manifests nicht Bereiche zu entfernen, es sei denn, Sie ersetzen sie durch eine geeignetere Alternative. z. B. ein enger gefasstes Projektumfang.

Hier finden Sie eine Liste mit Apps Script-Bereichen, die häufig in in Verbindung mit Google Workspace-Add-ons:

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 an externe Dienste zulassen https://www.googleapis.com/auth/script.external_request

Ermöglicht es dem Projekt, UrlFetch -Anfragen. Dies ist auch erforderlich, wenn das Projekt das <ph type="x-smartling-placeholder"></ph> OAuth2 für Apps Script-Bibliothek.

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 . Zugriff auf Sprache und Zeitzone des Nutzers, um weitere Informationen zu erhalten.

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

Ermöglicht dem Projekt, <ph type="x-smartling-placeholder"></ph> Trigger.

Vorschau von Drittanbieter-Links 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 damit interagiert. Weitere Informationen finden Sie unter . Vorschaulinks mit Smartchips anzeigen.

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, an die Nutzer gesendet werden das Formular zur Ressourcenerstellung und einen Link zur Ressource in einer Google Workspace-Anwendung einfügen. Weitere Informationen finden Sie unter . Über das @-Menü können Sie Ressourcen von Drittanbietern erstellen.