Autorisierungsbereiche

Nutzer müssen Skriptprojekte autorisieren, die auf ihre Daten zugreifen oder in ihrem Namen handeln. Eine allgemeine Übersicht über diesen Prozess finden Sie unter Autorisierung für Google-Dienste. Wenn ein Nutzer zum ersten Mal ein Skript ausführt, für das eine Autorisierung erforderlich ist, wird in der Benutzeroberfläche eine Aufforderung angezeigt, den Autorisierungsablauf zu starten.

Während dieses Ablaufs werden den Nutzern die Berechtigungen angezeigt, die das Skript anfordert. Ein Skript kann beispielsweise die Berechtigung zum Lesen von E-Mail-Nachrichten oder zum Erstellen von Kalenderterminen anfordern. Im Skriptprojekt werden diese einzelnen Berechtigungen als OAuth-Bereiche definiert.

Bei den meisten Skripts erkennt Apps Script automatisch die erforderlichen Bereiche. Sie können die von einem Skript verwendeten Bereiche jederzeit aufrufen. Sie können Bereiche auch explizit festlegen in Ihrem Manifest mithilfe von URL-Strings. Veröffentlichte Anwendungen wie Add-ons müssen die kleinstmöglichen Bereiche verwenden.

Während des Autorisierungsablaufs werden in Apps Script für Menschen lesbare Beschreibungen der erforderlichen Bereiche angezeigt. Wenn Ihr Skript beispielsweise schreibgeschützten Zugriff auf Tabellen benötigt, kann das Manifest den Bereich https://www.googleapis.com/auth/spreadsheets.readonly enthalten. In der Autorisierungsaufforderung werden Nutzer aufgefordert, „Ihre Google-Tabellen anzusehen“.

Einige Bereiche umfassen andere. Der autorisierte Zugriff auf https://www.googleapis.com/auth/spreadsheets ermöglicht beispielsweise Lese- und Schreibzugriff auf Tabellen.

Auf einigen Oberflächen wie der Apps Script-IDE wird Nutzern der detaillierte OAuth-Zustimmungsbildschirm angezeigt. Auf diesem Bildschirm können Nutzer bestimmte Berechtigungen auswählen, die sie erteilen möchten, anstatt alle Berechtigungen gleichzeitig zu erteilen. Entwerfen Sie Ihr Skript so, dass detaillierte OAuth-Berechtigungen verarbeitet werden können.

Bereiche ansehen

So sehen Sie die Bereiche, die für Ihr Skriptprojekt erforderlich sind:

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

Explizite Bereiche festlegen

In Apps Script werden die erforderlichen Bereiche automatisch ermittelt, indem der Code nach Funktionsaufrufen gescannt wird. Das ist für die meisten Skripts ausreichend, aber für veröffentlichte Add-ons, Web-Apps, Chat-Apps und Aufrufe der Chat API müssen Sie eine direktere Kontrolle ausüben.

In Apps Script werden manchmal automatisch permissive Bereiche zugewiesen. Das kann dazu führen, dass Ihr Skript Nutzer um mehr Zugriff bittet, als es benötigt. Ersetzen Sie bei veröffentlichten Skripts breite Bereiche durch eine begrenzte Anzahl von Bereichen, die die Anforderungen des Skripts abdecken.

Warnung: Verwenden Sie immer den am wenigsten permissiven Bereichssatz. Zum Schutz von Nutzerinformationen dürfen Add-ons und andere veröffentlichte Anwendungen nicht mehr Bereichsberechtigungen anfordern, als sie benötigen.

Sie können die Bereiche, die von Ihrem Skriptprojekt verwendet werden, explizit festlegen, indem Sie die Manifestdatei bearbeiten. Das Manifestfeld oauthScopes ist ein Array von Bereichen, die vom Projekt verwendet werden. So legen Sie die Bereiche Ihres Projekts fest:

1. Öffnen Sie das Skriptprojekt.
2. Klicken Sie links auf Projekteinstellungen .
3. Wählen Sie das Kästchen Manifestdatei „appsscript.json“ im Editor anzeigen aus.
4. Klicken Sie links auf Editor .
5. Klicken Sie links auf die Datei appsscript.json.
6. Suchen Sie das Feld der obersten Ebene mit der Bezeichnung oauthScopes. Wenn es nicht vorhanden ist, können Sie es hinzufügen.
7. Ersetzen Sie den Inhalt des Arrays oauthScopes durch die Bereiche, die das Projekt verwenden soll. Beispiel:

         {
           ...
           "oauthScopes": [
             "https://www.googleapis.com/auth/spreadsheets.readonly",
             "https://www.googleapis.com/auth/userinfo.email"
           ],
          ...
         }

8. Klicken Sie oben auf Speichern .

Detaillierte OAuth-Berechtigungen verarbeiten

Der detaillierte OAuth-Zustimmungsbildschirm wurde zuerst in der Apps Script-IDE für Nutzer eingeführt, die ein Skript direkt ausführen. Der Zustimmungsbildschirm wird im Laufe der Zeit schrittweise auf anderen Oberflächen wie Makros, Triggern und Add-ons eingeführt. Weitere Informationen finden Sie unter Detaillierte OAuth-Zustimmung bei Ausführungen in der Google Apps Script-IDE.

Auf dem detaillierten OAuth-Zustimmungsbildschirm können Nutzer angeben, welche einzelnen OAuth-Bereiche sie autorisieren möchten. So haben Nutzer detaillierte Kontrolle darüber, welche Kontodaten sie für jedes Skript freigeben. Wenn ein Skript beispielsweise E-Mail- und Kalenderbereiche anfordert, können Nutzer die Berechtigung für Google Kalender erteilen, aber nicht für Gmail.

In den folgenden Abschnitten wird beschrieben, wie Sie detaillierte OAuth-Berechtigungen verarbeiten.

Berechtigung für erforderliche Bereiche automatisch anfordern

Wenn für einen Ausführungsablauf bestimmte Bereiche erforderlich sind, können Sie Nutzer auffordern, diese Berechtigungen zu erteilen. Ihr Skript kann nach Berechtigungen suchen und sie automatisch anfordern, wenn sie fehlen.

Mit den folgenden Methoden der ScriptApp Klasse werden Berechtigungen validiert und die Autorisierungsaufforderung gerendert:

• requireScopes(authMode, oAuthScopes): Verwenden Sie diese Methode für Abläufe, die auf bestimmten Bereichen basieren.
• requireAllScopes(authMode): Verwenden Sie diese Methode, wenn ein Ausführungsablauf auf allen Projektbereichen basiert.

Beispiel

Das folgende Beispiel zeigt, wie Sie requireScopes() und requireAllScopes() aufrufen. Das Skript verwendet Bereiche für Gmail, Google Tabellen und Google Kalender. Für die Funktion sendEmail() sind nur die Bereiche für Gmail und Google Tabellen erforderlich, während für die Funktion createEventSendEmail() alle vom Skript verwendeten Bereiche erforderlich sind.

// This function requires the Gmail and Sheets scopes.
function sendEmail() {
  // Validates that the user has granted permission for the Gmail and Sheets scopes.
  // If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://mail.google.com/',
    'https://www.googleapis.com/auth/spreadsheets'
  ]);

  // Sends an email.
  GmailApp.sendEmail("[e-mail]", "Subject", "Body");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue("Sent");
  Logger.log("Sheet updated successfully!");
}

// This function requires all scopes used by the script (Gmail,
// Calendar, and Sheets).
function createEventSendEmail() {
  // Validates that the user has granted permission for all scopes used by the
  // script. If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

  // Creates an event.
  CalendarApp.getDefaultCalendar().createEvent(
    "Meeting",
    new Date("November 28, 2024 10:00:00"),
    new Date("November 28, 2024 11:00:00")
  );
  Logger.log("Calendar event created successfully!");

  // Sends an email.
  GmailApp.sendEmail("[e-mail]", "Subject 2", "Body 2");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the created meeting and sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email and Meeting Tracker")
  // Gets the last row
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row
  sheet.getRange(lastRow, 5).setValue("Sent");
  // Adds "Meeting created" to column F of the last row
  sheet.getRange(lastRow, 6).setValue("Meeting created");
  Logger.log("Sheet updated successfully!");
}

Benutzerdefinierte Benachrichtigungen für fehlende Bereiche erstellen

Sie können den Berechtigungsstatus von Nutzern abrufen und benutzerdefinierte Benachrichtigungen erstellen. Sie können beispielsweise Funktionen deaktivieren, für die fehlende Berechtigungen erforderlich sind, oder ein Dialogfeld anzeigen, in dem die Anforderung erläutert wird. Mit den folgenden Methoden wird ein Objekt mit den Berechtigungsinformationen des Nutzers abgerufen, das die vom Nutzer autorisierten Bereiche und eine URL zum Anfordern fehlender Bereiche enthält:

• getAuthorizationInfo(authMode, oAuthScopes): Prüft den Berechtigungsstatus für bestimmte Bereiche.
• getAuthorizationInfo(authMode): Prüft den Berechtigungsstatus für alle Projektbereiche.

Verwenden Sie die Methoden der AuthorizationInfo Klasse, um die Berechtigungsdetails aus dem Autorisierungsinformationsobjekt abzurufen, z. B. die Liste der autorisierten Bereiche und die URL zum Anfordern fehlender Berechtigungen.

Beispiel

Das folgende Beispiel zeigt, wie Sie mit getAuthorizationInfo() Funktionen überspringen, für die Nutzer die erforderlichen Bereiche nicht erteilt haben. So kann der Rest des Ausführungsablaufs fortgesetzt werden, ohne dass eine Autorisierung der fehlenden Bereiche angefordert wird.

// This function uses the Gmail scope and skips the email
// capabilities if the scope for Gmail hasn't been granted.
function myFunction() {
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);
  if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {
    GmailApp.sendEmail("[e-mail]", "Subject", "Body");
    Logger.log("Email sent successfully!");
  } else {
    const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();
    console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);
  }
  // Continue the rest of the execution flow...
}

Sicherstellen, dass Triggerausführungen Berechtigungen haben

Funktionen, die mit Triggern verknüpft sind, werden automatisch ausgeführt und Nutzer sind möglicherweise nicht anwesend, um Berechtigungen zu erteilen. Wir empfehlen, requireScopes(authMode, oAuthScopes) zu verwenden, bevor Sie einen Trigger installieren. So werden Nutzer aufgefordert, fehlende Berechtigungen zu erteilen, und der Trigger kann nicht ohne diese installiert werden.

Beispiel

// This function requires scope Sheets.
function trackFormSubmissions(e){
  // Opens a spreadsheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Submission Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds email address of user that submitted the form
  // to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue(e.name);
  Logger.log("Sheet updated successfully!");
}

function installTrigger(){
  // Validates that the user has granted permissions for trigger
  // installation and execution. If not, trigger doesn't get
  // installed and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://www.googleapis.com/auth/script.scriptapp',
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/forms.currentonly'
  ]);
  ScriptApp.newTrigger('trackFormSubmission')
    .forForm(FormApp.getActiveForm())
    .onFormSubmit()
    .create();
}

OAuth-Überprüfung

Bestimmte OAuth-Bereiche sind vertraulich , da sie Zugriff auf Daten von Google-Nutzern ermöglichen. Wenn Ihr Skriptprojekt Bereiche verwendet, die Zugriff auf Nutzerdaten ermöglichen, muss das Projekt die OAuth-Clientüberprüfung durchlaufen, bevor Sie es öffentlich als Web-App oder Add-on veröffentlichen können. Weitere Informationen finden Sie in folgenden Anleitungen:

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

Eingeschränkte Bereiche

Neben vertraulichen Bereichen werden bestimmte Bereiche als eingeschränkt klassifiziert und unterliegen zusätzlichen Regeln, die zum Schutz von Nutzerdaten beitragen. Wenn Sie eine App veröffentlichen, die eingeschränkte Bereiche verwendet, muss sie alle Spezifikationen erfüllen.

Sehen Sie sich vor der Veröffentlichung die vollständige Liste der eingeschränkten Bereiche an. Konforme Apps müssen die zusätzlichen Anforderungen für bestimmte API-Bereiche erfüllen.

Vermeiden Sie nach Möglichkeit die Verwendung eingeschränkter Bereiche, um den Überprüfungsprozess zu vereinfachen. Sie können eingeschränkte Bereiche für nicht öffentliche Apps uneingeschränkt verwenden.