Autorisierungsbereiche

Nutzer müssen Scriptprojekte autorisieren, die auf ihre Daten zugreifen oder in ihrem Namen handeln. Wenn ein Nutzer ein Script ausführt, für das zum ersten Mal eine Autorisierung erforderlich ist, wird auf der Benutzeroberfläche eine Aufforderung zum Starten des Autorisierungsvorgangs angezeigt.

Während dieses Vorgangs wird dem Nutzer auf der Benutzeroberfläche angezeigt, für welche Aktionen das Script die Berechtigung benötigt. Ein Script benötigt beispielsweise möglicherweise die Berechtigung, die E-Mail-Nachrichten des Nutzers zu lesen oder Ereignisse in seinem Kalender zu erstellen. Im Script-Projekt werden diese einzelnen Berechtigungen als OAuth-Bereiche definiert.

Bei den meisten Scripts erkennt Apps Script automatisch, welche Bereiche für Sie erforderlich sind. Sie können sich jederzeit die Bereiche ansehen, die in einem Script verwendet werden. Sie können Bereiche auch explizit in Ihrem manifest mithilfe von URL-Strings festlegen. Für bestimmte Anwendungen wie Add-ons ist es manchmal erforderlich, Bereiche explizit festzulegen, da für veröffentlichte Anwendungen immer der möglichst eng gefasste Bereich verwendet werden sollte.

Während des Autorisierungsvorgangs werden dem Nutzer in Apps Script lesbare Beschreibungen der erforderlichen Bereiche angezeigt. Wenn Ihr Script beispielsweise Lesezugriff 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 Script mit diesem Umfang gefragt, ob er dieser Anwendung erlauben möchte, „Ihre Google-Tabellen anzusehen“.

Einige Bereiche umfassen andere. Wenn der Umfang https://www.googleapis.com/auth/spreadsheets beispielsweise autorisiert ist, kann er Lese- und Schreibzugriff auf Tabellen haben.

Auf einigen Oberflächen, auf denen Scripts ausgeführt werden, z. B. wenn ein Script direkt über die Apps Script IDE ausgeführt wird, wird Nutzern der detaillierte OAuth-Zustimmungsbildschirm angezeigt. So können Nutzer bestimmte Berechtigungen gewähren, anstatt alle Berechtigungen auf einmal zu gewähren. Es ist wichtig, dass dein Script detaillierte OAuth-Berechtigungen verarbeitet.

Bereiche ansehen

So rufen Sie die Bereiche auf, die für Ihr Scriptprojekt derzeit erforderlich sind:

1. Öffnen Sie das Script-Projekt.
2. Klicken Sie links auf Übersicht info_outline.
3. Sie finden die Bereiche unter OAuth-Bereiche des Projekts.

Ausdrückliche Bereiche festlegen

In Apps Script wird automatisch ermittelt, welche Bereiche ein Script benötigt, indem der Code nach Funktionsaufrufen gescannt wird, für die sie erforderlich sind. Für die meisten Scripts ist das ausreichend und spart Zeit. Bei veröffentlichten Add-ons, Web-Apps, Google Chat-Apps und Aufrufen der Google Chat API müssen Sie die Berechtigungen jedoch direkter verwalten.

In Apps Script werden Projekten manchmal automatisch sehr weitreichende Berechtigungen zugewiesen. Das kann dazu führen, dass Ihr Script den Nutzer um mehr Informationen bittet, als für die Ausführung erforderlich sind. Das ist nicht empfehlenswert. Bei veröffentlichten Scripts müssen Sie weit gefasste Bereiche durch eine begrenztere Auswahl ersetzen, die nur die Anforderungen des Scripts erfüllt.

Sie können die Bereiche, die in Ihrem Scriptprojekt verwendet werden, explizit festlegen, indem Sie die manifest bearbeiten. Das Manifestfeld oauthScopes ist ein Array aller Bereiche, die vom Projekt verwendet werden. So legen Sie die Bereiche Ihres Projekts fest:

1. Öffnen Sie das Script-Projekt.
2. Klicken Sie links auf Projekteinstellungen settings.
3. Klicken Sie das Kästchen Manifestdatei „appsscript.json“ im Editor anzeigen an.
4. Klicken Sie links auf Editor code.
5. Klicken Sie links auf die Datei appsscript.json.
6. Suchen Sie das Feld der obersten Ebene mit der Bezeichnung oauthScopes. Wenn sie nicht vorhanden ist, können Sie sie hinzufügen.
7. Im Feld oauthScopes wird ein Array von Strings angegeben. Wenn Sie die Bereiche festlegen möchten, die für Ihr Projekt verwendet werden, ersetzen Sie den Inhalt dieses Arrays durch die gewünschten Bereiche. Beispiel:

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

8. Klicken Sie oben auf „Speichern“ (save).

Detaillierte OAuth-Berechtigungen verarbeiten

Auf dem detaillierten OAuth-Zustimmungsbildschirm können Nutzer angeben, welche einzelnen OAuth-Bereiche sie autorisieren möchten. Detaillierte OAuth-Berechtigungen geben Nutzern mehr Kontrolle darüber, welche Kontodaten sie für jedes Script freigeben möchten. Angenommen, Sie entwickeln ein Script, das die Berechtigung für den E-Mail- und den Kalenderbereich anfordert. Ihre Nutzer möchten Ihr Script möglicherweise nur für die Funktionen mit Google Kalender, aber nicht für Gmail verwenden. Mit detaillierten OAuth-Berechtigungen können Nutzer festlegen, dass nur die Berechtigung für Google Kalender, aber nicht für Gmail gewährt wird.

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

Berechtigung für erforderliche Bereiche automatisch anfordern

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

Mit den folgenden Methoden der Klasse ScriptApp kannst du die Berechtigung für die erforderlichen Bereiche prüfen und den Autorisierungsaufforderung automatisch anzeigen lassen, um fehlende Berechtigungen anzufordern:

• requireScopes(authMode, oAuthScopes): Verwenden Sie diese Methode für Ablaufabläufe, die auf einem oder mehreren, aber nicht auf allen Zugriffsbereichen basieren, die in Ihrem Script verwendet werden.
• requireAllScopes(authMode): Verwenden Sie diese Methode, wenn ein Ausführungsablauf auf allen Bereichen basiert, die in Ihrem Script 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 Google Tabellen erforderlich, während für die Funktion createEventSendEmail() alle Bereiche erforderlich sind, die vom Script verwendet werden.

// 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 Umgebung für fehlende Bereiche erstellen

Sie können die Berechtigungsdetails des Nutzers abrufen, der Ihr Script ausführt, und eine benutzerdefinierte Umgebung basierend auf seinem Berechtigungsstatus entwerfen. Sie können beispielsweise bestimmte Funktionen Ihres Scripts deaktivieren, für die Berechtigungen erforderlich sind, die der Nutzer nicht gewährt hat, oder ein benutzerdefiniertes Dialogfeld mit einer Erklärung zu den fehlenden Berechtigungen anzeigen. Mit den folgenden Methoden wird ein Objekt mit den Berechtigungsinformationen des Nutzers abgerufen. Dazu gehören die Berechtigungsbereiche, die der Nutzer autorisiert hat, und eine URL, über die Sie fehlende Berechtigungsbereiche 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 Bereiche prüfen, die in Ihrem Script verwendet werden.

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 Klasse AuthorizationInfo.

Beispiel

Das folgende Beispiel zeigt, wie die Methode getAuthorizationInfo(authMode, oAuthScopes) aufgerufen wird, um bestimmte Funktionen innerhalb eines Ausführungsablaufs zu überspringen, für die die erforderlichen Bereiche nicht gewährt wurden. So kann der Rest des Ausführungsablaufs fortgesetzt werden, ohne dass eine Autorisierung für die fehlenden Bereiche erforderlich ist.

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

OAuth-Überprüfung

Bestimmte OAuth-Bereiche sind sensibel, da sie Zugriff auf Nutzerdaten von Google gewähren. Wenn Ihr Scriptprojekt Bereiche verwendet, die den Zugriff auf Nutzerdaten ermöglichen, muss das Projekt OAuth-Client-Überprüfung bestehen, bevor Sie es öffentlich als Webanwendung oder Add-on veröffentlichen können. Weitere Informationen finden Sie in folgenden Leitfäden:

• OAuth-Clientüberprüfung für Apps Script
• Nicht bestätigte Apps
• Häufig gestellte Fragen zur OAuth-Überprüfung
• Google APIs-Dienst: Richtlinie zu Nutzerdaten

Eingeschränkter Geltungsbereich

Neben sensiblen Bereichen werden bestimmte Bereiche als eingeschränkt klassifiziert und unterliegen zusätzlichen Regeln zum Schutz von Nutzerdaten. Wenn Sie eine Webanwendung oder ein Add-on veröffentlichen möchten, das einen oder mehrere eingeschränkte Bereiche verwendet, 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, etwas zu veröffentlichen. Wenn Ihre App eine dieser APIs verwendet, müssen Sie vor der Veröffentlichung die zusätzlichen Anforderungen für bestimmte API-Bereiche erfüllen.