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

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

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

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

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

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

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

Обзор областей

Чтобы увидеть области действия, необходимые для вашего скриптового проекта:

1. Откройте проект скрипта.
2. Слева нажмите «Обзор .
3. Список областей действия можно посмотреть в разделе Project OAuth Scopes .

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

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

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

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

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

1. Откройте проект скрипта.
2. В левой части экрана нажмите проекта» .
3. Установите флажок «Показать файл манифеста "appsscript.json" в редакторе» .
4. Слева нажмите «Редактор .
5. Слева нажмите на файл appsscript.json .
6. Найдите поле верхнего уровня с меткой oauthScopes . Если его нет, вы можете его добавить.
7. Замените содержимое массива oauthScopes на области действия, которые вы хотите использовать в проекте. Например:

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

8. Вверху нажмите «Сохранить .

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

Детальный экран согласия OAuth первоначально запускался в среде разработки Apps Script для пользователей, непосредственно выполняющих скрипт. Со временем этот экран согласия постепенно становится доступен и для других интерфейсов, таких как макросы, триггеры и дополнения. Для получения дополнительной информации см. раздел «Детальное согласие OAuth при выполнении скриптов в среде разработки Google Apps Script» .

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

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

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

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

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

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

Пример

В следующем примере показано, как вызывать функции requireScopes() и requireAllScopes() . Скрипт использует области видимости для Gmail, Sheets и Calendar. Функция sendEmail() требует только области видимости для Gmail и Sheets, в то время как функция 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("[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!");
}

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

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

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

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

Пример

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

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

Убедитесь, что для выполнения триггеров установлены соответствующие разрешения.

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

Пример

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

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

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

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

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

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

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