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

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

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

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

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

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

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

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

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

Состояния дополнения редактора

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

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

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

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

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

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

Если в файле, форме, презентации или электронной таблице включена надстройка редактора, 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 соответствует константе в перечислении Apps Script ScriptApp.AuthMode .

Режимы авторизации применяются ко всем методам выполнения 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() (только в Таблицах)	Пользовательские функции	Все остальное время, в том числе: устанавливаемые триггеры onInstall() google.script.run
Доступ к данным пользователя	Только локаль	Только локаль	Только локаль	Да
Доступ к документу, форме, презентации или таблице	Нет	Да	Да — только для чтения	Да
Доступ к пользовательскому интерфейсу	Добавить пункты меню	Добавить пункты меню	Нет	Да
Доступ к Properties	Нет	Да	Да	Да
Доступ к Jdbc , UrlFetch	Нет	Нет	Да	Да
Другие услуги	Logger Utilities	Любые сервисы, которые не имеют доступа к пользовательским данным	Любые сервисы, которые не имеют доступа к пользовательским данным	Все услуги

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

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

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

Когда надстройка редактора устанавливается из магазина, ее функция 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. Сохраните код и создайте тестовое развертывание.

   При создании тестового развертывания убедитесь, что в поле «Конфигурация» указано «Установлено для текущего пользователя» и что текст под полем «Конфигурация» содержит надпись «Тестировать в AuthMode.None

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

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

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

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