Области применения

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

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

Вы объявляете области действия (scopes) в манифесте , используя 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. Список областей действия можно посмотреть в разделе "Области действия Project OAuth".

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

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

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

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

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

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

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

4. Поле oauthScopes задаёт массив строк. Чтобы задать области действия (scopes), используемые вашим проектом, замените содержимое этого массива на нужные вам области действия. Например, для дополнения 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 для Apps Script
• Непроверенные приложения
• Часто задаваемые вопросы о проверке OAuth
• Сервис Google API: Политика обработки пользовательских данных

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

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

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

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

Расширение Google Workspace Developer Tools для Visual Studio Code предоставляет диагностическую информацию для всех областей действия, включая описание области и информацию о том, является ли она конфиденциальной или ограниченной.

Выберите области действия для дополнений Google Workspace.

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

Области редактора

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

Примечание: Данная область currentonly доступна только в рамках служб Apps Script. Она не включает расширенные службы Apps Script или прямые вызовы API Google Workspace.

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

Гмайл

Для защиты данных пользователей Gmail в дополнениях Google Workspace было создано несколько областей действия (scopes). Эти области действия необходимо явно добавить в манифест дополнения, наряду с любыми другими, которые требуются кодом дополнения.

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

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

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

Объем
Метаданные события доступа	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 Chat

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

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

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

Метод	Поддерживается аутентификация пользователя	Поддерживается аутентификация приложения	Поддерживаемые области авторизации
Отправить сообщение			При аутентификации пользователя : chat.messages.create chat.messages chat.import С аутентификацией приложения : chat.bot
Создайте пространство			При аутентификации пользователя : chat.spaces.create chat.spaces chat.import С аутентификацией приложения и подтверждением администратора (доступно в предварительной версии для разработчиков ): chat.app.spaces.create chat.app.spaces
Создавайте и добавляйте участников в пространство.		—	При аутентификации пользователя : chat.spaces.create chat.spaces
Добавить пользователя в пространство			При аутентификации пользователя : chat.memberships chat.memberships.app chat.import С аутентификацией приложения и подтверждением администратора (доступно в предварительной версии для разработчиков ): chat.app.memberships
Список мероприятий или событий из чата		—	При аутентификации пользователя необходимо использовать область действия (scope) для каждого типа события , включенного в запрос: Информация о мероприятиях, связанных с сообщениями: chat.messages chat.messages.readonly Информация о мероприятиях, связанных с реакциями: chat.messages.reactions chat.messages.reactions.readonly chat.messages chat.messages.readonly Информация о мероприятиях, связанных с членством: chat.memberships chat.memberships.readonly Информация о мероприятиях, связанных с этим пространством: chat.spaces chat.spaces.readonly

Области действия Google Drive

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

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

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

Для защиты пользовательских данных области действия 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

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

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

Объем
Прочитать адрес электронной почты пользователя	https://www.googleapis.com/auth/userinfo.email Позволяет проекту считывать адрес электронной почты текущего пользователя.
Разрешить вызовы внешних служб	https://www.googleapis.com/auth/script.external_request Позволяет проекту выполнять запросы UrlFetch . Это также необходимо, если проект использует библиотеку OAuth2 for Apps Script .
Прочитать локаль и часовой пояс пользователя.	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. Для получения дополнительной информации см. раздел «Создание сторонних ресурсов из меню @» .