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

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

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

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

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

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

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

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

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

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

Gmail

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

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

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

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

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

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

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

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

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

Области Google Диска

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

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

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

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

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