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

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

Модель авторизации надстроек редактора более сложная. Поскольку эти надстройки работают с файлами, хранящимися на Google Диске — файлами, которыми можно поделиться с другими, — вы должны создавать надстройки редактора с учетом различных режимов авторизации . Приложения-редакторы Google Workspace также предоставляют меню надстроек в своих пользовательских интерфейсах, которое заполняется установленными вами надстройками, даже если вы еще не авторизовали эти надстройки. Это усложняет модель авторизации.

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

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

  • Как только вы получите надстройку редактора из магазина, вы увидите ее в меню надстроек для каждого документа, который вы открываете или создаете. Соавторы этих документов не увидят надстройку, кроме как в документах, где вы ее используете .
  • После того как вы используете надстройку редактора в документе, ваши соавторы также увидят ее в меню надстроек, но только для этого документа (если они также не установили эту надстройку).

Эта модель обмена кажется естественной для большинства пользователей. Однако, поскольку надстройка редактора автоматически запускает onOpen(e) для добавления пунктов меню при открытии документа, описанное выше поведение усложняет правила авторизации Apps Script. В конце концов, пользователям будет неудобно, если надстройка будет получать доступ к личным данным каждый раз, когда они открывают документ. Это руководство должно помочь вам понять, что и когда может делать ваш код.

Установлено против включено

Если вы видите надстройку редактора в меню, она находится в одном (или в обоих) из двух состояний: установлено и включено. Надстройка редактора устанавливается для конкретного пользователя после того, как он выбирает надстройку в магазине и разрешает ей доступ к своим данным Google. Напротив, надстройка включается в данном документе , когда кто-либо использует ее там. Если два человека совместно работают над документом, и один из них использует надстройку, она устанавливается для одного пользователя и активируется для документа.

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

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

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

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

В частности, установленное и включенное состояния определяют, в каком режиме авторизации работает функция onOpen(e) . Сценарий приложений передает режим авторизации как свойство authMode параметра события сценария приложений e ; значение e.authMode соответствует константе в перечислении Apps ScriptApp.AuthMode .

Если в текущем документе включена надстройка редактора, onOpen(e) запускается в AuthMode.LIMITED . Если надстройка не включена и только установлена, onOpen(e) запускается в AuthMode.NONE .

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

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

Полный жизненный цикл

Если надстройка либо установлена ​​для текущего пользователя, либо включена в текущем документе, надстройка загружается в документ, в результате чего она появляется в меню надстроек и начинает прослушивать простые триггеры onInstall(e) , onOpen(e) и onEdit(e) . Если пользователь щелкает один из пунктов меню надстройки, она запускает .

Установка

Когда надстройка редактора устанавливается из магазина, ее onInstall(e) запускается в AuthMode.FULL . Это позволяет надстройке выполнять сложную процедуру установки, но важно также использовать onInstall(e) для создания элементов меню, поскольку документ уже открыт и, следовательно, ваша onOpen(e) не запущена. Для удобства вы можете просто вызвать onOpen(e) из onInstall(e) , как показано в этом примере:

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

Открытие

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

Если надстройка создает только базовое меню, режим не имеет значения. В этом примере показано, как может выглядеть простой onOpen(e) :

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

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

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();
}

Бег

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