Области авторизации для надстроек редактора

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

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

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

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

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

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

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

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

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

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

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

  1. Просмотрите области действия, которые в настоящее время использует ваше дополнение . Определите, какие изменения необходимо внести, например, использовать более узкую область действия.
  2. Откройте файл манифеста вашего дополнения .
  3. Найдите поле верхнего уровня с надписью oauthScopes . Если его нет, вы можете его добавить.

  4. Поле oauthScopes содержит массив строк. Чтобы задать области действия, используемые вашим проектом, замените содержимое этого массива на нужные вам области действия. Например, для надстройки «Редактор», расширяющей возможности Таблиц, может быть следующее:

    {
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.container.ui",
    "https://www.googleapis.com/auth/spreadsheets"
  ],
  ...
}

  5. Сохраните изменения файла манифеста.

Проверка OAuth

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

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

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

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

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

Области действия надстроек редактора

При создании дополнения «Редактор» необходимые области действия определяются службой Apps Script и методами, используемыми кодом дополнения. Например, для дополнения «Таблицы» может потребоваться область действия https://www.googleapis.com/auth/spreadsheets.readonly для чтения информации из разных таблиц Google.

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

Если вы не задаете области действия явно и ваш редактор выполняет только чтение или запись в открытый файл редактора, добавьте следующий комментарий в один из файлов проекта скрипта:

  /**
   * @OnlyCurrentDoc
   */

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