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:
- Öffnen Sie das Skriptprojekt.
- Klicken Sie links auf Übersicht.
- 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:
- Aktuell vom Add-on verwendete Bereiche ansehen Bestimmen Sie, was müssen Änderungen vorgenommen werden, z. B. die Verwendung eines engeren Rahmens.
- Öffnen Sie die Manifestdatei des Add-ons.
- Suchen Sie das oberste Feld mit der Bezeichnung
oauthScopes
. Ist dies nicht der Fall, können Sie es hinzufügen. 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" ], ... }
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:
- OAuth-Client-Überprüfung für Apps Script
- Nicht überprüfte Apps
- Häufig gestellte Fragen zur OAuth-Bestätigung
- Google APIs-Dienst: Nutzerdatenrichtlinie
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>
|
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>
|
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. |
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 |
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,
|
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. |