Сферы

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

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

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

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

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

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

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

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

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

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

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

См. пример запроса доступа к выбранным файлам .

Область действия дополнений 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

Предоставляет временный доступ к метаданным открытого сообщения (например, к теме или получателям). Не разрешает чтение содержимого сообщения и требует токена доступа.

Требуется, если надстройка использует метаданные в триггерах действия создания. Для действий создания эта область необходима, если триггеру создания требуется доступ к метаданным. На практике эта область позволяет создавать списки получателей доступа к триггеру (кому:, копия: и скрытая копия:) черновика ответа электронной почты.

Читать содержимое открытого сообщения 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

Требуется, если надстройка обращается к Apps Script Docs API. Предоставляет временный доступ к содержимому открытого документа.

Доступ к файлу текущих таблиц 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 и если надстройка получает доступ к REST API Документов, Таблиц, Слайдов или Диска . Предоставляет пофайловый доступ к файлам, созданным или открытым приложением, с помощью службы Apps Script Advanced Drive Service . Однако это не позволяет использовать аналогичные действия с помощью базовой службы Диска . Авторизация файла предоставляется для каждого файла отдельно и отменяется, когда пользователь деавторизует приложение.

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

Для вашей надстройки могут потребоваться дополнительные области, если она использует другие службы 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

Позволяет проекту создавать триггеры .