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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 , как описано в следующей таблице.

Жизненный цикл авторизации дополнения 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 завершается неудачей. Если опубликованное дополнение не добавляет пункты меню, проверьте консоль браузера, чтобы узнать, была ли возвращена ошибка. Затем изучите свой скрипт, чтобы определить, вызывают ли функция 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. Возможно, вы пропустили обращение в службу поддержки.

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

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