Прицелы, прицелы, прицелы

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

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

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

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

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

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

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

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

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

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

Например, 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
• Служба Google API: политика в отношении пользовательских данных

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

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

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

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

Области календаря

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

Объем
Доступ к метаданным событий	https://www.googleapis.com/auth/calendar.addons.execute Требуется, если надстройка получает доступ к метаданным событий календаря. Разрешает надстройке доступ к метаданным событий.
Чтение данных о событиях, созданных пользователем	https://www.googleapis.com/auth/calendar.addons.current.event.read Требуется, если надстройке необходимо считывать данные о событиях, созданных пользователем. Позволяет надстройке получать доступ к данным о событиях, созданных пользователем. Эти данные доступны только в том случае, если для поля манифеста addOns.calendar.eventAccess установлено значение READ или READ_WRITE .
Запись данных о событиях, созданных пользователем	https://www.googleapis.com/auth/calendar.addons.current.event.write Требуется, если надстройке необходимо записывать данные о событиях, созданных пользователем. Позволяет надстройке редактировать данные о событиях, созданные пользователем. Эти данные доступны только в том случае, если для поля манифеста addOns.calendar.eventAccess установлено значение WRITE или READ_WRITE .

Области диска

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

Объем
Чтение метаданных выбранного элемента	https://www.googleapis.com/auth/drive.addons.metadata.readonly Требуется, если надстройка реализует контекстный интерфейс, который активируется, когда пользователь выбирает объекты на Диске. Позволяет надстройке считывать ограниченные метаданные об элементах, которые пользователь выбрал на Google Диске. Метаданные ограничиваются идентификатором элемента, заголовком, типом MIME, URL-адресом значка и наличием у надстройки разрешения на доступ к элементу.
Доступ к каждому файлу	https://www.googleapis.com/auth/drive.file Рекомендуется, если надстройке требуется доступ к отдельным файлам на Диске. Предоставляет пофайловый доступ к файлам, созданным или открытым приложением, с помощью службы Apps Script Advanced Drive . Однако это не позволяет использовать аналогичные действия с использованием базовой службы Диска . Авторизация файла предоставляется отдельно для каждого файла и аннулируется, когда пользователь отменяет авторизацию приложения. См . пример запроса доступа к выбранным файлам .

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

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

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

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

Объем
Создание новых черновиков	https://www.googleapis.com/auth/gmail.addons.current.action.compose Требуется, если надстройка использует триггеры действий создания . Позволяет надстройке временно создавать новые черновики сообщений и ответов. Подробности см. в разделе Создание черновиков сообщений ; эта область также часто используется с действиями создания . Требуется токен доступа.
Чтение метаданных открытого сообщения	https://www.googleapis.com/auth/gmail.addons.current.message.metadata Предоставляет временный доступ к метаданным открытого сообщения (например, к теме или получателям). Не позволяет читать содержимое сообщения и требует маркер доступа. Требуется, если надстройка использует метаданные в триггерах действий создания. Для действий создания эта область требуется, если триггеру создания требуется доступ к метаданным. На практике эта область позволяет составлять списки получателей триггерного доступа (to:, cc: и bcc:) в черновике ответного электронного письма.
Прочитать содержимое открытого сообщения	https://www.googleapis.com/auth/gmail.addons.current.message.action Предоставляет доступ к содержимому открытого сообщения при взаимодействии с пользователем, например, при выборе пункта меню надстройки. Требуется токен доступа.
Прочитать содержимое открытой темы	https://www.googleapis.com/auth/gmail.addons.current.message.readonly Предоставляет временный доступ к метаданным и содержимому открытого сообщения. Также предоставляет доступ к содержимому других сообщений в открытой теме. Требуется токен доступа.
Чтение любого содержимого сообщения и метаданных	https://www.googleapis.com/auth/gmail.readonly Прочитайте любые метаданные и содержимое электронной почты, включая открытое сообщение. Требуется, если вам нужно прочитать информацию о других сообщениях, например, при выполнении поискового запроса или чтении всей почтовой цепочки. Внимание : это очень широкая и ограниченная область применения . Используйте его только в случае крайней необходимости.

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

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

Примечание. Токен доступа, который включает области Gmail, не совпадает с токеном доступа, возвращаемым ScriptApp.getOAuthToken() . Вы должны использовать токен, предоставленный в объекте события действия.

Ниже показан пример установки токена доступа для разрешения доступа к метаданным сообщения. Единственная область, необходимая для этого примера, — 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, которые расширяют возможности Документов, Таблиц и Презентаций.

Объем
Текущий доступ к файлу Документов	https://www.googleapis.com/auth/documents.currentonly Требуется, если надстройка обращается к API Apps Script Docs. Предоставляет временный доступ к содержимому открытого документа.
Доступ к файлу текущих таблиц	https://www.googleapis.com/auth/spreadsheets.currentonly Требуется, если надстройка обращается к API таблиц сценариев приложений. Предоставляет временный доступ к содержимому открытой таблицы.
Доступ к текущему файлу слайдов	https://www.googleapis.com/auth/presentations.currentonly Требуется, если надстройка обращается к API Apps Script Slides. Предоставляет временный доступ к содержимому открытой презентации.
Доступ к каждому файлу	https://www.googleapis.com/auth/drive.file Требуется, чтобы надстройка использовала onFileScopeGrantedTrigger и имела ли надстройка доступ к Docs, Sheets, Slides или Drive API . Предоставляет пофайловый доступ к файлам, созданным или открытым приложением, с помощью службы Apps Script Advanced Drive . Однако это не позволяет использовать аналогичные действия с использованием базовой службы Диска . Авторизация файла предоставляется отдельно для каждого файла и аннулируется, когда пользователь отменяет авторизацию приложения.

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

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

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

Объем
Прочитать адрес электронной почты пользователя	https://www.googleapis.com/auth/userinfo.email Позволяет проекту читать адрес электронной почты текущего пользователя.
Разрешить вызовы на внешние службы	https://www.googleapis.com/auth/script.external_request Позволяет проекту выполнять запросы UrlFetch . Это также необходимо, если в проекте используется библиотека сценариев OAuth2 для приложений .
Чтение локали и часового пояса пользователя	https://www.googleapis.com/auth/script.locale Позволяет проекту узнать локаль и часовой пояс текущего пользователя. Подробности см. в разделе Доступ к локали и часовому поясу пользователя .
Создание триггеров	https://www.googleapis.com/auth/script.scriptapp Позволяет проекту создавать триггеры .
Предварительный просмотр сторонних ссылок	https://www.googleapis.com/auth/workspace.linkpreview Требуется, если дополнение просматривает ссылки со стороннего сервиса. Позволяет проекту видеть ссылку в приложении Google Workspace, пока пользователь взаимодействует с ним. Дополнительные сведения см. в разделе Предварительный просмотр ссылок со смарт-чипами .
Создание сторонних ресурсов	https://www.googleapis.com/auth/workspace.linkcreate Требуется, если надстройка создает ресурсы в стороннем сервисе. Позволяет проекту читать информацию, которую пользователи отправляют в форму создания ресурса, и вставлять ссылку на ресурс в приложение Google Workspace. Дополнительные сведения см. в разделе Создание сторонних ресурсов из меню @ .