Авторизация надстройки редактора

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

Модель авторизации для дополнений редактора более сложна по нескольким причинам:

• Когда пользователь создает файл, все установленные им дополнения отображаются в меню «Расширения» , даже если пользователь еще не авторизовал эти дополнения.

• Эти дополнения работают с файлами в Google Drive, которыми можно делиться с соавторами. Соавторы, у которых не установлено дополнение Editor, видят его в документах, где его использовал создатель файла.

• Дополнения к редактору автоматически запускают свои функции onOpen() при открытии документа.

Для защиты пользовательских данных применяются режимы авторизации, которые делают некоторые сервисы недоступными для метода onOpen() . Это руководство поможет вам понять, что может делать ваш код и когда.

модель авторизации

Режим авторизации дополнения Editor зависит от его состояния, которое, в свою очередь, зависит от того, кто его использует: пользователь, установивший дополнение, или соавтор.

Надстройка редактора гласит:

Установлены ли, включены или и то, и другое дополнения редактора, перечисленные в меню «Расширения» .

• Дополнение устанавливается для конкретного пользователя после того, как он или его администратор получит его из Google Workspace Marketplace и разрешит ему доступ к своим данным Google.
• Дополнение активируется в документе, форме, презентации или электронной таблице, когда кто-либо использует его там.
• Когда пользователи совместно работают над файлом, и один из них использует надстройку, она устанавливается для этого пользователя и активируется для файла.

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

	Установлено	Включено
Применяется к	Пользователь	Документ, форма, презентация или электронная таблица
Вызвано	Получение дополнения из магазина	Получение дополнения из магазина во время работы с этим документом, формой, презентацией или электронной таблицей, или Использование ранее установленного дополнения в этом документе, форме, презентации или электронной таблице.
Меню отображается для	Только этот пользователь, во всех документах, формах, презентациях или электронных таблицах, которые он открывает или создает, может получить доступ к этим документам.	Все участники, работавшие над этим документом, формой, презентацией или электронной таблицей.
Режим авторизации для onOpen()	AuthMode.NONE (если только оно также не включено , в этом случае AuthMode.LIMITED)	AuthMode.LIMITED

режимы авторизации

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

Если в файле, форме, презентации или электронной таблице включено дополнение Editor, onOpen() выполняется в AuthMode.LIMITED . Если дополнение не включено, а только установлено , onOpen() выполняется в AuthMode.NONE .

В AuthMode.NONE дополнение не может запускать определенные службы, пока пользователь не взаимодействует с дополнением, щелкая мышью или запуская пользовательские функции. Если ваше дополнение попытается использовать эти службы в onOpen() , onInstall() или в глобальной области видимости, произойдет сбой разрешений, и другие вызовы, такие как заполнение меню, прекратятся . Единственным поддерживаемым вариантом является справка.

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

Примечание: Только опубликованные дополнения для редактора могут находиться в режиме AuthMode.NONE ; неопубликованные дополнения для редактора запускаются onOpen() в режиме авторизации AuthMode.LIMITED . Однако вы можете протестировать дополнение для редактора , чтобы убедиться, что разрабатываемое дополнение работает должным образом в любом из режимов авторизации.

Apps Script передает режим авторизации в качестве свойства authMode параметра события Apps Script, e ; значение e.authMode соответствует константе в перечислении ScriptApp.AuthMode объекта Apps Script.

Режимы авторизации применяются ко всем методам выполнения Apps Script, включая запуск из редактора скриптов, из пункта меню или из вызова Apps Script google.script.run . Однако свойство e.authMode можно проверить только в том случае, если скрипт выполняется в результате триггера, такого как onOpen() , onEdit() или onInstall() . Пользовательские функции в Google Sheets используют собственный режим авторизации AuthMode.CUSTOM_FUNCTION , который похож на LIMITED , но имеет несколько иные ограничения. Во всех остальных случаях скрипты выполняются в AuthMode.FULL , как описано в следующей таблице.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
Происходит при	onOpen() (если пользователь установил надстройку, но не активировал ее в документе, форме, презентации или электронной таблице)	onOpen() (во все остальные моменты времени) onEdit() (только в Google Sheets)	Пользовательские функции	Все остальные случаи, включая: устанавливаемые триггеры onInstall() google.script.run
Доступ к пользовательским данным	Только для локали	Только для локали	Только для локали	Да
Доступ к документу, форме, презентации или электронной таблице.	Нет	Да	Да — только для чтения	Да
Доступ к пользовательскому интерфейсу	Добавить пункты меню	Добавить пункты меню	Нет	Да
Доступ к Properties	Нет	Да	Да	Да
Доступ к Jdbc и UrlFetch	Нет	Нет	Да	Да
Другие услуги	Logger Utilities	Любые сервисы, которые не имеют доступа к пользовательским данным.	Любые сервисы, которые не имеют доступа к пользовательским данным.	Все услуги

Жизненный цикл авторизации дополнения Editor

Когда надстройка устанавливается для текущего пользователя или активируется в текущем файле, она загружается для документа, формы, презентации или электронной таблицы при открытии этого файла. Надстройка отображается в меню «Расширения» и начинает отслеживать простые триггеры onInstall() , onOpen() и onEdit() . Если пользователь щелкает по пункту меню «Расширения» , выполняется соответствующий код.

Дополнение Editor установлено.

При установке дополнения Editor из магазина его функция onInstall() выполняется в AuthMode.FULL . В этом режиме авторизации дополнение может выполнять сложную процедуру настройки. Также следует использовать onInstall() для создания пунктов меню, поскольку документ, форма, презентация или электронная таблица уже открыты, и ваша функция onOpen() еще не была запущена. Следующий пример показывает, как вызвать функцию onOpen() из функции onInstall() :

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

Дополнение «Редактор» открыто.

При открытии документа, формы, презентации или электронной таблицы загружаются все надстройки редактора, установленные текущим пользователем или включенные любым из соавторов в файле, и вызываются соответствующие функции onOpen() . Режим авторизации, в котором работает функция onOpen() зависит от того, установлена ​​или включена надстройка.

Если дополнение создает только базовое меню, режим работы не имеет значения. В следующем примере показана базовая функция onOpen() :

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

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

В следующем примере показана расширенная функция onOpen() , которая изменяет свое действие в зависимости от режима авторизации:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

Предупреждение: При выполнении функции onOpen() загружается весь скрипт, и все глобальные операторы выполняются в том же режиме авторизации, что и onOpen() . Если режим авторизации запрещает глобальные операторы, выполнение как глобальных операторов, так и функции onOpen() завершится неудачей. Если опубликованное дополнение не добавляет пункты меню, проверьте консоль JavaScript браузера, чтобы узнать, была ли возвращена ошибка. Затем изучите свой скрипт, чтобы определить, вызывает ли функция onOpen() или глобальные переменные сервисы, которые не разрешены в AuthMode.NONE .

Обратите внимание, что дополнения не могут открывать боковые панели или диалоговые окна при выполнении в AuthMode.LIMITED . Вы можете использовать пункты меню для открытия боковых панелей и диалоговых окон, поскольку они работают в режиме AuthMode.FULL .

Пользователь запускает надстройку «Редактор».

Когда пользователь нажимает на пункт меню «Расширения» , Apps Script сначала проверяет, установил ли пользователь надстройку, и предлагает ему сделать это, если нет. Если пользователь авторизовал надстройку, скрипт запускает функцию, соответствующую пункту меню в AuthMode.FULL . Надстройка включается в документ, форму, презентацию или электронную таблицу, если она еще не была включена.

Устранение неполадок, связанных с неотображением меню дополнений.

Меню вашего дополнения может не отображаться, если ваш код неправильно обрабатывает режимы авторизации. Например:

• Дополнение пытается запустить службу Apps Script, которая не поддерживается текущим режимом авторизации.

• Дополнение пытается выполнить вызов сервиса до того, как пользователь начнет с ним взаимодействовать.

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

1. Откройте проект Apps Script для вашего дополнения и найдите функцию onOpen() .
2. Найдите в функции onOpen() упоминания служб Apps Script или связанных с ними объектов, таких как PropertiesService , SpreadsheetApp или GmailApp .
3. Если сервис используется не для создания элементов пользовательского интерфейса, удалите его или заключите в блок комментариев. Оставьте только следующие методы: .getUi() , .createMenu() , .addItem() и .addToUi() . Также найдите и удалите любой сервис, находящийся вне функции.
4. Определите функции, которые могут содержать строки кода, закомментированные или удаленные на предыдущем шаге, особенно те, которые используют получаемую ими информацию, и перенесите вызовы сервисов в функции, которые в них нуждаются. Перестройте или перепишите свой код, чтобы учесть изменения, внесенные на предыдущих шагах.

5. Сохраните код и создайте тестовое развертывание.

   При создании тестового развертывания убедитесь, что в поле «Config» указано «Установлено для текущего пользователя» , а под полем «Config» написано «Test in AuthMode.None

6. Запустите тестовую установку и откройте меню «Расширения» .

7. Если отображаются все пункты меню, проблема решена. Если вы видите только меню «Справка» , вернитесь к шагу 1. Возможно, вы пропустили обращение в сервисную службу.

Связанные темы

• Веб-приложения
• Типы дополнений
• Протестируйте дополнение для редактора.