Область авторизации

Пользователи должны авторизовать проекты сценариев, которые получают доступ к их данным или действуют от их имени. Когда пользователь впервые запускает сценарий, требующий авторизации, пользовательский интерфейс отображает запрос на запуск процесса авторизации.

Во время этого процесса пользовательский интерфейс сообщает пользователю, на какие действия сценарий хочет получить разрешение. Например, сценарию может потребоваться разрешение на чтение сообщений электронной почты пользователя или создание событий в его календаре. Проект скрипта определяет эти отдельные разрешения как области OAuth .

Для большинства сценариев Apps Script автоматически определяет, какие области вам необходимы; вы можете в любое время просмотреть области, используемые сценарием. Вы также можете явно указать области действия в своем манифесте, используя строки URL. Явная установка областей действия иногда требуется для некоторых приложений, например надстроек , поскольку опубликованные приложения всегда должны использовать максимально узкие области действия.

Во время процесса авторизации Apps Script предоставляет пользователю удобочитаемые описания необходимых областей. Например, если вашему сценарию требуется доступ к вашим электронным таблицам только для чтения, манифест может иметь область действия https://www.googleapis.com/auth/spreadsheets.readonly . Во время процесса авторизации сценарий с этой областью запрашивает у пользователя разрешение этому приложению «Просматривать ваши таблицы Google».

Некоторые области включают в себя другие. Например, при авторизации область https://www.googleapis.com/auth/spreadsheets разрешает доступ для чтения и записи к электронным таблицам.

Для некоторых поверхностей, где выполняются сценарии, например запуск сценария непосредственно из Apps Script IDE, пользователям предоставляется детальный экран согласия OAuth. Это позволяет пользователям выбирать конкретные разрешения для предоставления, а не предоставлять все разрешения одновременно. Важно разработать сценарий для детальной обработки разрешений OAuth .

Просмотр областей

Вы можете увидеть области действия, которые в настоящее время требуются вашему проекту сценария, выполнив следующие действия:

1. Откройте проект сценария.
2. Слева нажмите Обзор info_outline .
3. Просмотрите области в разделе «Области действия OAuth проекта» .

Установите явные области действия

Apps Script автоматически определяет, какие области действия нужны сценарию, сканируя его код на наличие вызовов функций, которые в них нуждаются. Для большинства скриптов этого достаточно и экономит ваше время, но для опубликованных надстроек, веб-приложений, приложений Google Chat и вызовов API Google Chat вам необходимо осуществлять более прямой контроль над областями.

Apps Script иногда автоматически назначает проектам очень широкие возможности. Это может означать, что ваш скрипт запрашивает у пользователя больше, чем ему нужно, что является плохой практикой. Для опубликованных сценариев необходимо заменить широкие области более ограниченным набором, отвечающим потребностям сценария, и не более того.

Вы можете явно указать области действия, которые использует ваш проект сценария, отредактировав его файл манифеста . Поле манифеста oauthScopes представляет собой массив всех областей, используемых проектом. Чтобы установить области действия вашего проекта, выполните следующие действия:

1. Откройте проект сценария.
2. Слева нажмите settings параметров проекта .
3. Установите флажок Показывать файл манифеста «appsscript.json» в редакторе .
4. Слева нажмите « code редактора» .
5. Слева щелкните файл appsscript.json .
6. Найдите поле верхнего уровня с надписью oauthScopes . Если его нет, вы можете его добавить.
7. Поле oauthScopes указывает массив строк. Чтобы установить области, которые использует ваш проект, замените содержимое этого массива областями, которые вы хотите использовать. Например:

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

8. Вверху нажмите save .

Обработка детальных разрешений OAuth

Экран детального согласия OAuth позволяет пользователям указать, какие отдельные области OAuth они хотят авторизовать. Детализированные разрешения OAuth дают пользователям более детальный контроль над тем, какими данными учетной записи они хотят поделиться с каждым скриптом. Например, представьте, что вы разрабатываете сценарий, который запрашивает разрешение как для электронной почты, так и для области календаря. Ваши пользователи могут захотеть использовать ваш скрипт только из-за его возможностей с Календарем Google, но не с Gmail. Благодаря детальным разрешениям OAuth пользователи могут предоставить разрешение только Календарю, но не Gmail.

В следующих разделах описаны основные способы обработки детальных разрешений OAuth.

Автоматически требовать разрешения для необходимых областей

Если для работы потока выполнения требуется разрешение на области, вы можете потребовать от пользователей предоставить эти разрешения, прежде чем они смогут его использовать. Ваш скрипт может проверить, предоставил ли пользователь уже разрешение, и, если нет, автоматически запросить его.

Следующие методы класса ScriptApp позволяют проверять разрешения для необходимых областей и автоматически отображать запрос на авторизацию для запроса недостающих разрешений:

• requireScopes(authMode, oAuthScopes) : используйте этот метод для потоков выполнения, которые полагаются на одну или несколько областей, но не на все области, используемые вашим скриптом.
• requireAllScopes(authMode) : используйте этот метод, если поток выполнения зависит от всех областей, используемых вашим скриптом.

Пример

В следующем примере показано, как вызвать методы requireScopes(authMode, oAuthScopes) и requireAllScopes(authMode) . Скрипт использует области действия для Gmail, Таблиц и Календаря. Для функции sendEmail() требуются только области действия Gmail и Таблиц, а для функции createEventSendEmail() требуются все области действия, используемые сценарием.

// 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!");
}

Создайте индивидуальный интерфейс для отсутствующих областей

Вы можете получить сведения о разрешениях пользователя, запускающего ваш сценарий, и разработать индивидуальный интерфейс на основе статуса его разрешений. Например, вы можете решить отключить определенные функции вашего скрипта, требующие разрешений, которые пользователь не предоставил, или представить настраиваемое диалоговое окно с объяснением недостающих разрешений. Следующие методы получают объект с информацией о разрешениях пользователя, которая включает в себя области, авторизованные пользователем, и URL-адрес, по которому можно запросить недостающие области:

• getAuthorizationInfo(authMode, oAuthScopes) : используйте этот метод для проверки статуса разрешений для определенных областей.
• getAuthorizationInfo(authMode) : используйте этот метод, чтобы проверить статус разрешений для всех областей, используемых вашим скриптом.

Чтобы получить сведения о разрешениях из объекта информации об авторизации, например список разрешенных областей и URL-адрес для запроса недостающих разрешений, используйте методы класса AuthorizationInfo .

Пример

В следующем примере показано, как вызвать метод getAuthorizationInfo(authMode, oAuthScopes) для пропуска определенных функций в потоке выполнения, где необходимые области не были предоставлены. Это позволяет продолжить выполнение остальной части потока выполнения без запроса авторизации недостающих областей.

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

Некоторые области действия OAuth являются конфиденциальными , поскольку они разрешают доступ к пользовательским данным Google. Если ваш проект скрипта использует области, которые разрешают доступ к пользовательским данным, проект должен пройти проверку клиента OAuth, прежде чем вы сможете опубликовать его публично в качестве веб-приложения или надстройки . Для получения дополнительной информации см. следующие руководства:

• Проверка клиента OAuth для скрипта приложений
• Непроверенные приложения
• Часто задаваемые вопросы по проверке OAuth
• Служба Google API: политика в отношении пользовательских данных

Ограниченные области применения

Помимо конфиденциальных областей, некоторые области классифицируются как ограниченные , и на них распространяются дополнительные правила, помогающие защитить пользовательские данные. Если вы собираетесь опубликовать веб-приложение или надстройку , использующую одну или несколько ограниченных областей, перед публикацией приложение должно соответствовать всем указанным ограничениям.

Прежде чем пытаться опубликовать, просмотрите полный список ограниченных областей . Если ваше приложение использует какой-либо из них, вы должны соблюдать дополнительные требования для конкретных областей API перед публикацией.