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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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