Сферы

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

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

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

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

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

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

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

Установка явных областей

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

Например, Apps Script может предоставить проекту сценария надстройки очень разрешающую область действия https://mail.google.com по умолчанию. Когда пользователь авторизует проект скрипта с этой областью действия, проекту предоставляется полный доступ к учетной записи Gmail пользователя. Для опубликованных надстроек вы должны заменить эту область более ограниченным набором, который покрывает потребности надстройки и не более того.

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

1. Просмотрите области действия, которые в настоящее время использует ваша надстройка . Определите, какие изменения необходимо внести, например, сузив область действия.
2. Откройте файл манифеста надстройки .
3. Найдите поле верхнего уровня с надписью oauthScopes . Если его нет, то можно добавить.

4. Поле oauthScopes указывает массив строк. Чтобы установить области, которые использует ваш проект, замените содержимое этого массива областями, которые вы хотите использовать. Например, для надстройки Google Workspace, которая расширяет возможности Gmail, у вас может быть следующее:

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     ...
   }
   

5. Сохраните изменения файла манифеста.

Проверка OAuth

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

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

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

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

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

Календарные области

Ниже приведены часто используемые области надстроек Google Workspace, которые расширяют Календарь Google.

Дисковые области

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

Область действия дополнений Gmail

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

Ниже приведены часто используемые области действия надстроек Google Workspace, расширяющих возможности Gmail. те, которые помечены как обязательные , должны быть добавлены в манифест надстройки Google Workspace, если ваша надстройка расширяет возможности Gmail.

Не забудьте также заменить очень широкую область действия https://mail.google.com в своем дополнении более узким набором областей действия, которые обеспечивают взаимодействие, необходимое вашему дополнению, и не более того.

Токены доступа

Для защиты пользовательских данных области Gmail, используемые в надстройках Google Workspace, предоставляют только временный доступ к пользовательским данным. Чтобы включить временный доступ, вы должны вызвать функцию GmailApp.setCurrentMessageAccessToken(accessToken) , используя токен доступа в качестве аргумента. Вы должны получить токен доступа из объекта события действия .

Ниже показан пример установки маркера доступа для разрешения доступа к метаданным сообщения. Единственная область действия, необходимая для этого примера, — это https://www.googleapis.com/auth/gmail.addons.current.message.metadata .

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Область действия редактора

Ниже приведены часто используемые области дополнений Google Workspace, которые расширяют возможности Документов, Таблиц и Презентаций.

Другие области применения

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

Для справки, вот список областей действия скрипта приложений, которые часто используются в сочетании с надстройками Google Workspace: