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

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

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

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

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

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

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

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.currentonly"
     ],
     ...
   }
   

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

Проверка OAuth

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

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

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

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

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

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

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

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

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

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

  /**
   * @OnlyCurrentDoc
   */

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