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

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

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

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

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

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

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

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

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

Редактор областей

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

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

Объем
Доступ к файлам текущих документов	https://www.googleapis.com/auth/documents.currentonly Требуется, если надстройка обращается к API Apps Script Docs. Предоставляет временный доступ к содержимому открытого документа.
Доступ к файлам текущих таблиц	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 . Предоставляет пофайловый доступ к файлам, созданным или открытым приложением, с помощью Apps Script Advanced Drive Service . Однако это не позволяет использовать аналогичные действия с использованием базовой службы 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 Читать любые метаданные и содержимое электронной почты, включая открытое сообщение. Требуется, если вам нужно прочитать информацию о других сообщениях, например, при выполнении поискового запроса или чтении всей ветки писем. Предупреждение : Это очень широкая, ограниченная область применения . Используйте ее только в случае крайней необходимости.

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

Ниже приведены часто используемые области действия дополнений 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 Chat

Developer Preview: доступно в рамках программы Google Workspace Developer Preview , которая предоставляет ранний доступ к определенным функциям.

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

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

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

Метод	Поддерживается аутентификация пользователя	Поддерживается аутентификация приложения	Поддерживаемые области авторизации
Отправить сообщение			С аутентификацией пользователя : chat.messages.create chat.messages chat.import С аутентификацией через приложение : chat.bot
Создать пространство			С аутентификацией пользователя : chat.spaces.create chat.spaces chat.import С аутентификацией приложения и одобрением администратора (доступно в версии Developer Preview ): chat.app.spaces.create chat.app.spaces
Создание и добавление участников в пространство		—	С аутентификацией пользователя : chat.spaces.create chat.spaces
Добавить пользователя в пространство			С аутентификацией пользователя : chat.memberships chat.memberships.app chat.import С аутентификацией приложения и одобрением администратора (доступно в версии Developer Preview ): chat.app.memberships
Перечислите действия или события из чат-пространства		—	При аутентификации пользователя необходимо использовать область действия для каждого типа событий, включенного в запрос: Для событий, связанных с сообщениями: 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 Диска

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

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

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

Для защиты пользовательских данных области 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. Чтобы узнать больше, см. Создание сторонних ресурсов из меню @ .