Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

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

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

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

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

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

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

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

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

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

Просмотрите области, которые в настоящее время использует ваше дополнение . Определите, какие изменения необходимо внести, например, использовать более узкую область применения.
Откройте файл манифеста вашего дополнения .
Найдите поле верхнего уровня с надписью oauthScopes . Если его нет, вы можете его добавить.
Поле oauthScopes указывает массив строк. Чтобы установить области, которые использует ваш проект, замените содержимое этого массива областями, которые вы хотите использовать. Например, для надстройки Google Workspace, расширяющей Gmail, у вас может быть следующее:
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}
```
Сохраните изменения файла манифеста.

Проверка OAuth

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

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

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

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

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

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

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

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

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

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

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

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

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

Объем
Прочитать адрес электронной почты пользователя	`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. Дополнительные сведения см. в разделе Создание сторонних ресурсов из меню @ .