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

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

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

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

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

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

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

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

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

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

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