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 Autorisierungsvorgang zu starten.

Während dieses Ablaufs wird dem Nutzer in der Aufforderung mitgeteilt, wozu die Anwendung eine Berechtigung 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 möglicherweise 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 von einem Add-on mit diesem Bereich aufgefordert, dem Add-on zu erlauben, E‑Mails abzurufen, wenn das Add-on ausgeführt wird.

Die Bereiche, die Apps Script für die verschiedenen Dienste verwendet, überschneiden sich mit den Bereichen der zugehörigen API. Der Apps Script-Kalenderdienst verwendet beispielsweise viele der gleichen Bereiche wie die Calendar API. In der Apps Script-Referenzdokumentation finden Sie die Bereiche, die für bestimmte Apps Script-Dienstmethoden erforderlich sind.

Bereiche ansehen

So können Sie die Berechtigungsbereiche sehen, die für Ihr Skriptprojekt derzeit erforderlich sind:

1. Öffnen Sie das Skriptprojekt.
2. Klicken Sie links auf Übersicht info_outline.
3. 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 Skripts ist das ausreichend und spart Ihnen Zeit. Bei veröffentlichten Add-ons sollten Sie jedoch mehr direkte Kontrolle über die Bereiche haben.

In Apps Script wird einem Add-on-Scriptprojekt beispielsweise standardmäßig der sehr permissive Bereich https://mail.google.com zugewiesen. Wenn ein Nutzer ein Skriptprojekt 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:

1. Bereiche ansehen, die von Ihrem Add-on verwendet werden Legen Sie fest, welche Änderungen vorgenommen werden müssen, z. B. ein engerer Umfang.
2. Manifestdatei des Add-ons öffnen
3. Suchen Sie das Feld der obersten Ebene mit dem Label oauthScopes. Wenn sie nicht vorhanden ist, können Sie sie hinzufügen.

4. 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"
      ],
      ...
    }
   

5. 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:

• OAuth-Clientüberprüfung für Apps Script
• Nicht überprüfte Apps
• Häufig gestellte Fragen zur OAuth-Überprüfung
• Google APIs-Dienste: Nutzerdatenrichtlinie

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, Ihre App zu veröffentlichen. 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.

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 Frage, 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

Die folgenden häufig verwendeten Bereiche für Google Workspace-Add-ons erweitern Google Docs, Google Sheets und Google Präsentationen.

Gmail

Es gibt speziell für Google Workspace-Add-ons erstellte Bereiche, die zum Schutz von Gmail-Nutzerdaten beitragen. Fügen Sie diese Bereiche explizit dem Add-on-Manifest hinzu, zusammen mit allen anderen erforderlichen Bereichen.

In der folgenden Tabelle sind häufig verwendete Bereiche für Google Workspace-Add-ons aufgeführt, die Gmail erweitern. Wenn Ihr Add-on Gmail erweitert, müssen Sie alle Bereiche, die mit Erforderlich gekennzeichnet sind, in das Manifest Ihres Google Workspace-Add-ons aufnehmen.

Ersetzen Sie den allgemeinen Bereich https://mail.google.com durch eine eingeschränktere Gruppe von Bereichen, die die für Ihr Add-on erforderlichen Interaktionen ermöglichen.

Google Kalender-Bereiche

In der folgenden Tabelle sind häufig verwendete Bereiche für Google Workspace-Add-ons aufgeführt, die Google Kalender erweitern.

Google Chat-Bereiche

Wenn Sie die Google Chat API aufrufen möchten, müssen Sie sich als Google Chat-Nutzer oder als Google 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 Authentifizierungsmethoden 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:

Google Drive-Bereiche

In der folgenden Tabelle sind häufig verwendete Bereiche für Google Workspace-Add‑ons aufgeführt, die Google Drive erweitern.

Zugriffstokens

Zum Schutz von Nutzerdaten gewähren die in Google Workspace-Add-ons verwendeten Gmail-Bereiche temporären Zugriff auf Nutzerdaten. Wenn Sie den temporären Zugriff aktivieren möchten, rufen Sie GmailApp.setCurrentMessageAccessToken mit einem Zugriffstoken aus einem Aktionsereignisobjekt auf.

Das Zugriffstoken, das Gmail-Bereiche ermöglicht, ist nicht dasselbe wie das Zugriffstoken, das von ScriptApp.getOAuthToken zurückgegeben wird. Verwenden Sie das Token, das im Aktionsereignisobjekt bereitgestellt wird.

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 erkennt Apps Script diese Bereiche und aktualisiert das Manifest automatisch. Entfernen Sie beim Bearbeiten der Bereichsliste Ihres Manifests keine Bereiche, es sei denn, Sie ersetzen sie durch eine eingeschränktere Alternative.

In der folgenden Tabelle sind Bereiche aufgeführt, die häufig von Google Workspace-Add-ons verwendet werden: