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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Функция onOpen() надстройки «Редактор» запускается автоматически при открытии пользователем документа, формы, презентации или электронной таблицы. Для защиты данных пользователей Apps Script ограничивает возможности функции onOpen() . Состояние надстройки «Редактор» определяет режим авторизации, в котором выполняется функция 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		 Любые сервисы, не имеющие доступа к пользовательским данным Любые сервисы, не имеющие доступа к пользовательским данным Все услуги

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

Если надстройка установлена для текущего пользователя или включена в текущем файле, она загружается для документа, формы, презентации или электронной таблицы при открытии этого файла. Надстройка отображается в меню «Расширения» и начинает прослушивать простые триггеры 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();
}

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

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

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

Когда пользователь щёлкает по пункту меню « Расширения» , 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. Возможно, вы пропустили обращение в сервисный центр.