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 den Nutzern in der Benutzeroberfläche angezeigt, welche Berechtigungen das Skript anfordert. Ein Skript kann beispielsweise die Berechtigung zum Lesen von E‑Mails oder zum Erstellen von Kalenderterminen anfordern. Im Skriptprojekt werden diese einzelnen Berechtigungen als OAuth-Bereiche definiert.

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

Während des Autorisierungsvorgangs werden in Apps Script menschenlesbare 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 wird der Nutzer aufgefordert, „Ihre Google-Tabellen anzusehen“.

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

Auf einigen Oberflächen, z. B. in der Apps Script IDE, sehen Nutzer den detaillierten OAuth-Zustimmungsbildschirm. Auf diesem Bildschirm können Nutzer bestimmte Berechtigungen auswählen, die sie gewähren möchten, anstatt alle Berechtigungen auf einmal zu gewähren. Entwerfen Sie Ihr Skript so, dass detaillierte OAuth-Berechtigungen verarbeitet werden.

Bereiche ansehen

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

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

Explizite Bereiche festlegen

Apps Script ermittelt die erforderlichen Bereiche automatisch, indem der Code nach Funktionsaufrufen durchsucht 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 die Kontrolle direkter ausüben.

In Apps Script werden manchmal automatisch Berechtigungen mit weitreichenden Berechtigungsbereichen zugewiesen. Das kann bedeuten, dass Ihr Skript Nutzer um mehr Zugriff bittet, als es benötigt. Ersetzen Sie in veröffentlichten Skripts umfassende Bereiche durch eine begrenzte Gruppe, die den Anforderungen des Skripts entspricht.

Sie können die von Ihrem Skriptprojekt verwendeten Bereiche 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. Aktivieren Sie das Kästchen Manifestdatei „appsscript.json“ im Editor anzeigen.
  4. Klicken Sie 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. Ersetzen Sie den Inhalt des oauthScopes-Arrays 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. Die Einwilligungsaufforderung wird im Laufe der Zeit schrittweise für andere Oberflächen wie Makros, Trigger und Add-ons eingeführt. 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. So können Nutzer genau festlegen, welche Kontodaten sie für die einzelnen Skripts freigeben. Wenn ein Skript beispielsweise E-Mail- und Kalenderbereiche anfordert, können Nutzer die Kalenderberechtigung erteilen, aber nicht die Gmail-Berechtigung.

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

Automatisch Berechtigungen für erforderliche Bereiche anfordern

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

Die folgenden Methoden der Klasse ScriptApp prüfen Berechtigungen und rendern die Autorisierungsaufforderung:

Beispiel

Das folgende Beispiel zeigt, wie requireScopes() und requireAllScopes() aufgerufen werden. Das Script verwendet Bereiche für Gmail, Google Tabellen und Google Kalender. Für die Funktion sendEmail() sind nur die Berechtigungsbereiche für Gmail und Sheets erforderlich, während für die Funktion createEventSendEmail() alle vom Script verwendeten Berechtigungsbereiche 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("dana@example.com", "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("dana@example.com", "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 den Berechtigungsstatus von Nutzern abrufen und benutzerdefinierte Funktionen entwickeln. Sie können beispielsweise Funktionen deaktivieren, für die Berechtigungen fehlen, 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:

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

Beispiel

Das folgende Beispiel zeigt, wie Sie getAuthorizationInfo() verwenden, um Funktionen zu überspringen, für die Nutzer die erforderlichen Bereiche nicht gewährt 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("dana@example.com", "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...
}

Sorgen Sie dafür, dass Triggerausführungen Berechtigungen haben

Funktionen, die mit Triggern verknüpft sind, werden automatisch ausgeführt. Nutzer sind möglicherweise nicht anwesend, um 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 ermöglichen. Wenn in Ihrem Skriptprojekt Bereiche verwendet werden, die den Zugriff auf Nutzerdaten ermöglichen, muss das Projekt die OAuth-Client-Überprüfung durchlaufen, bevor Sie es öffentlich als Webanwendung oder Add-on veröffentlichen können. Weitere Informationen finden Sie in folgenden Anleitungen:

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 App veröffentlichen, in der eingeschränkte Bereiche verwendet werden, muss sie allen Spezifikationen entsprechen.

Vollständige Liste der eingeschränkten Bereiche vor der Veröffentlichung prüfen. Apps, die den Richtlinien entsprechen, müssen die zusätzlichen Anforderungen für bestimmte API-Bereiche erfüllen.

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