Autorisierungsbereiche

Nutzer müssen Skriptprojekte autorisieren, die auf ihre Daten zugreifen oder in ihrem Namen handeln. 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 Autorisierungsvorgang zu starten.

Während dieses Ablaufs wird dem Nutzer in der Benutzeroberfläche mitgeteilt, wofür das Script eine Berechtigung benötigt. Ein Script kann beispielsweise die Berechtigung zum Lesen der E-Mail-Nachrichten des Nutzers oder zum Erstellen von Ereignissen in seinem Kalender anfordern. Im Skriptprojekt werden diese einzelnen Berechtigungen als OAuth-Bereiche definiert.

Bei den meisten Skripts erkennt Apps Script automatisch, welche Bereiche benötigt werden. Sie können die von einem Skript verwendeten Bereiche jederzeit ansehen. Sie können Bereiche auch explizit in Ihrem Manifest mit URL-Strings festlegen. Für bestimmte Anwendungen wie Add-ons ist es manchmal erforderlich, Bereiche explizit festzulegen, da für veröffentlichte Anwendungen immer die engstmöglichen Bereiche verwendet werden sollten.

Während des Autorisierungsvorgangs werden dem Nutzer in Apps Script lesbare Beschreibungen der erforderlichen Bereiche angezeigt. Wenn Ihr Skript beispielsweise schreibgeschützten Zugriff auf Ihre Tabellen benötigt, kann das Manifest den Bereich https://www.googleapis.com/auth/spreadsheets.readonly haben. Während des Autorisierungsvorgangs wird der Nutzer von einem Skript mit diesem Bereich aufgefordert, dieser Anwendung die Berechtigung zu erteilen, seine Google-Tabellen anzusehen.

Einige Bereiche umfassen andere. Wenn der Bereich https://www.googleapis.com/auth/spreadsheets autorisiert ist, ermöglicht er beispielsweise Lese- und Schreibzugriff auf Tabellen.

Auf einigen Oberflächen, auf denen Skripts ausgeführt werden, z. B. wenn ein Skript direkt über die Apps Script-IDE ausgeführt wird, wird Nutzern der detaillierte OAuth-Zustimmungsbildschirm angezeigt. So können Nutzer bestimmte Berechtigungen auswählen, die sie gewähren möchten, anstatt alle Berechtigungen auf einmal zu gewähren. Es ist wichtig, dass Sie Ihr Skript so gestalten, dass es detaillierte OAuth-Berechtigungen verarbeiten kann.

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 .
3. Die Bereiche finden Sie unter Project OAuth Scopes (OAuth-Bereiche des Projekts).

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, Web-Apps, Google Chat-Apps und Aufrufen der Google Chat API müssen Sie jedoch eine direktere Kontrolle über die Bereiche ausüben.

In Apps Script werden Projekten manchmal automatisch sehr permissive Bereiche zugewiesen. Das kann bedeuten, dass Ihr Skript den Nutzer nach mehr Informationen fragt, als es benötigt. Das ist nicht empfehlenswert. Bei veröffentlichten Skripts müssen Sie die weit gefassten Bereiche durch eine eingeschränktere Gruppe ersetzen, die nur die Anforderungen des Skripts abdeckt.

Warnung :Verwenden Sie immer den geringstmöglichen Berechtigungssatz. Zum Schutz von Nutzerdaten sollten Add-ons und andere veröffentlichte Anwendungen niemals mehr Berechtigungen für Bereiche anfordern, als unbedingt erforderlich sind.

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

1. Öffnen Sie das Skriptprojekt.
2. Klicken Sie links auf Projekteinstellungen .
3. Klicken Sie das Kästchen Manifestdatei „appsscript.json“ im Editor anzeigen an.
4. Klicke links auf Editor .
5. Klicken Sie links auf die Datei appsscript.json.
6. Suchen Sie das Feld der obersten Ebene mit dem Label oauthScopes. Wenn sie nicht vorhanden ist, können Sie sie hinzufügen.
7. Das Feld oauthScopes gibt ein Array von Strings an. Um die Bereiche festzulegen, die Ihr Projekt verwendet, ersetzen Sie den Inhalt dieses Arrays durch die Bereiche, die Sie verwenden möchten. 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

Hinweis :Der detaillierte OAuth-Zustimmungsbildschirm wurde zuerst in der Apps Script-IDE für Nutzer eingeführt, die ein Skript direkt aus Apps Script ausführen. Die Einwilligungsaufforderung wird nach und nach auf die verbleibenden Oberflächen wie Makros, Triggerausführungen und Add-ons ausgeweitet. Weitere Informationen finden Sie unter Granular OAuth consent in Google Apps Script IDE executions.

Auf dem detaillierten OAuth-Zustimmungsbildschirm können Nutzer angeben, welche einzelnen OAuth-Bereiche sie autorisieren möchten. Mit detaillierten OAuth-Berechtigungen haben Nutzer mehr Kontrolle darüber, welche Kontodaten sie mit den einzelnen Skripts teilen möchten. Angenommen, Sie entwickeln ein Skript, das Berechtigungen für E-Mail- und Kalenderbereiche anfordert. Ihre Nutzer möchten Ihr Skript möglicherweise nur für die Funktionen in Google Kalender, aber nicht für Gmail verwenden. Mit detaillierten OAuth-Berechtigungen können Nutzer beispielsweise nur die Berechtigung für Google Kalender, aber nicht für Gmail erteilen.

In den folgenden Abschnitten werden die wichtigsten Möglichkeiten zum Umgang mit detaillierten OAuth-Berechtigungen beschrieben.

Automatisch Berechtigungen für erforderliche Bereiche anfordern

Wenn für einen Ausführungsablauf Berechtigungen für Bereiche erforderlich sind, können Sie festlegen, dass Nutzer diese Berechtigungen erteilen müssen, bevor sie den Ablauf verwenden können. Ihr Script kann prüfen, ob der Nutzer bereits die Berechtigung erteilt hat, und ihn gegebenenfalls automatisch darum bitten.

Mit den folgenden Methoden der ScriptApp-Klasse können Sie die Berechtigung für erforderliche Bereiche validieren und die Autorisierungsaufforderung automatisch rendern, um fehlende Berechtigungen anzufordern:

• requireScopes(authMode, oAuthScopes): Verwenden Sie diese Methode für Ausführungsabläufe, die auf einem oder mehreren Zugriffsbereichen basieren, aber nicht auf allen Zugriffsbereichen, die von Ihrem Skript verwendet werden.
• requireAllScopes(authMode): Verwenden Sie diese Methode, wenn ein Ausführungsablauf von allen Bereichen abhängt, die von Ihrem Skript verwendet werden.

Beispiel

Das folgende Beispiel zeigt, wie die Methoden requireScopes(authMode, oAuthScopes) und requireAllScopes(authMode) aufgerufen werden. Das Script verwendet Bereiche für Gmail, Google Tabellen und Google Kalender. Für die Funktion sendEmail() sind nur die Bereiche für Gmail und Sheets 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 Benachrichtigung für fehlende Bereiche erstellen

Sie können die Berechtigungsdetails des Nutzers abrufen, der Ihr Skript ausführt, und eine benutzerdefinierte Umgebung basierend auf seinem Berechtigungsstatus erstellen. Sie können beispielsweise bestimmte Funktionen Ihres Skripts deaktivieren, für die Berechtigungen erforderlich sind, die der Nutzer nicht erteilt hat, oder ein benutzerdefiniertes Dialogfeld anzeigen, in dem die fehlenden Berechtigungen erläutert werden. Die folgenden Methoden rufen ein Objekt mit den Berechtigungsinformationen des Nutzers ab, das die vom Nutzer autorisierten Bereiche und eine URL enthält, mit der Sie fehlende Bereiche anfordern können:

• getAuthorizationInfo(authMode, oAuthScopes): Mit dieser Methode können Sie den Berechtigungsstatus für bestimmte Bereiche prüfen.
• getAuthorizationInfo(authMode): Mit dieser Methode können Sie den Berechtigungsstatus für alle von Ihrem Skript verwendeten Bereiche prüfen.

Wenn Sie die Berechtigungsdetails aus dem Autorisierungsinformationsobjekt abrufen möchten, z. B. eine Liste der autorisierten Bereiche und eine URL zum Anfordern fehlender Berechtigungen, verwenden Sie die Methoden der AuthorizationInfo-Klasse.

Beispiel

Das folgende Beispiel zeigt, wie Sie die Methode getAuthorizationInfo(authMode, oAuthScopes) aufrufen, um bestimmte Funktionen in einem Ausführungsablauf zu überspringen, in dem die erforderlichen Bereiche nicht gewährt wurden. So kann der Rest des Ausführungsablaufs fortgesetzt werden, ohne dass die Autorisierung der fehlenden Bereiche angefordert werden muss.

// 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...
}

Berechtigungen für die Ausführung von Triggern

Funktionen, die mit Triggern verknüpft sind, können bei bestimmten Ereignissen automatisch ausgeführt werden. Der Nutzer ist dann möglicherweise nicht anwesend, um weitere Berechtigungen zu erteilen. Wir empfehlen, requireScopes(authMode, oAuthScopes) zu verwenden, bevor Sie einen Trigger installieren. Der Nutzer wird aufgefordert, fehlende Berechtigungen zu erteilen. Ohne diese Berechtigungen kann der Trigger nicht 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 gewähren. Wenn in Ihrem Scriptprojekt Bereiche verwendet werden, die den 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 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

Neben sensiblen Bereichen werden bestimmte Bereiche als eingeschränkt klassifiziert und unterliegen zusätzlichen Regeln, die zum Schutz von Nutzerdaten beitragen. Wenn Sie eine Web-App oder ein Add-on veröffentlichen möchten, in der bzw. dem ein oder mehrere eingeschränkte Bereiche verwendet werden, muss die App alle angegebenen Einschränkungen erfüllen, bevor sie veröffentlicht werden kann.

Sehen Sie sich die vollständige Liste der eingeschränkten Bereiche an, bevor Sie versuchen, die App zu veröffentlichen. Wenn Ihre App eine dieser APIs verwendet, müssen Sie vor der Veröffentlichung die zusätzlichen Anforderungen bei bestimmten API-Bereichen einhalten.

Hinweis :Vermeiden Sie nach Möglichkeit die Verwendung eingeschränkter Bereiche in Ihrer App. Es ist einfacher, die Überprüfung für die öffentliche Veröffentlichung zu bestehen, wenn Sie sie nicht verwenden. Sie können eingeschränkte Bereiche für nicht öffentliche Apps und Skripts uneingeschränkt verwenden.