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

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

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

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

Примечание: Данная область currentonly доступна только в рамках служб Apps Script. Она не включает расширенные службы Apps Script или прямые вызовы API Google Workspace.

Примечание: Области действия, используемые Apps Script для различных своих сервисов, частично совпадают с областями действия, используемыми соответствующим API. Например, сервис «Календарь » в Apps Script использует многие из тех же областей действия, что и API «Календарь» . Вы можете найти информацию об областях действия, необходимых для конкретных методов сервиса Apps Script, в справочной документации Apps Script.

Визуальные телескопы

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

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

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

Задание явных областей видимости

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

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

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

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

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

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

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

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

Проверка OAuth

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

• Проверка клиента OAuth для Apps Script
• Непроверенные приложения
• Часто задаваемые вопросы о проверке OAuth
• Сервис Google API: Политика обработки пользовательских данных

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

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

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

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

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

Дополнительные области действия редактора

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

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

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

  /**
   * @OnlyCurrentDoc
   */

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

Примечание: Данная область currentonly доступна только в рамках служб Apps Script. Она не включает расширенные службы Apps Script или прямые вызовы API Google Workspace.