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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 Таблицах используют собственный режим авторизации AuthMode.CUSTOM_FUNCTION , который похож на LIMITED , но имеет немного другие ограничения. Во всех остальных случаях скрипты запускаются в AuthMode.FULL , как описано в следующей таблице.

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

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

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

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

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

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

Открывается надстройка «Редактор»

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

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

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

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

В следующем примере показана расширенная функция 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();
}

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

Пользователь запускает надстройку Editor

Когда пользователь нажимает на пункт меню Extensions , 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. Возможно, вы пропустили вызов службы поддержки.