Авторизация для многих приложений на основе скриптов проста, поскольку проект скрипта запрашивает все недостающие разрешения, которые ему необходимы, когда кто-то пытается его использовать.
Модель авторизации для надстроек редактора более сложна по нескольким причинам:
Когда пользователь создает файл, все надстройки, которые он устанавливает, отображаются в меню «Расширения» , даже если пользователь еще не авторизовал эти надстройки.
Эти дополнения работают с файлами на 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()
или глобальной области, разрешения не будут предоставлены, а другие вызовы, такие как заполнение меню, будут остановлены . Помощь — единственный поддерживаемый вариант.
Для запуска ограниченных сервисных вызовов необходимо использовать режим авторизации 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
, как описано в следующей таблице.
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();
}
Обратите внимание, что надстройки не могут открывать боковые панели или диалоговые окна во время выполнения в AuthMode.LIMITED
. Вы можете использовать пункты меню для открытия боковых панелей и диалоговых окон, поскольку они запускаются в AuthMode.FULL
.
Пользователь запускает надстройку редактора
Когда пользователь щелкает пункт меню «Расширения» , Apps Script сначала проверяет, установил ли пользователь надстройку, и предлагает ему сделать это, если нет. Если пользователь авторизовал надстройку, скрипт запускает функцию, соответствующую пункту меню в AuthMode.FULL
. Надстройка включена в документе, форме, презентации или электронной таблице, если это еще не было сделано.
Устранение неполадок, из-за которых дополнительные меню не отображаются
Ваше дополнительное меню может не отображаться, если ваш код неправильно управляет режимами авторизации. Например:
Надстройка пытается запустить службу Apps Script, которая не поддерживается текущим режимом авторизации.
Надстройка пытается выполнить вызов службы до того, как с ней взаимодействует пользователь.
Чтобы удалить или изменить порядок вызова службы, вызывающего ошибки разрешений в AuthMode.NONE
, попробуйте выполнить следующие действия:
- Откройте проект Apps Script для вашего дополнения и найдите функцию
onOpen()
. - Найдите в функции
onOpen()
упоминания служб Apps Script или связанных с ними объектов, таких какPropertiesService
,SpreadsheetApp
илиGmailApp
. - Если служба используется для чего-либо, кроме создания элементов пользовательского интерфейса, удалите ее или оберните в блок комментариев. Оставьте только эти методы:
.getUi()
,.createMenu()
,.addItem()
и.addToUi()
. Также найдите и удалите любую службу, находящуюся за пределами функции. - Определите функции, которые могут содержать строки кода, закомментированные или удаленные на предыдущем шаге, особенно те, которые используют информацию, которую они производят, и переместите вызовы служб в функции, которые в них нуждаются. Перестройте или перепишите свою кодовую базу, чтобы учесть изменения, внесенные на предыдущих шагах.
Сохраните код и создайте тестовое развертывание.
При создании тестового развертывания убедитесь, что в поле «Конфигурация» установлено значение «Установлено для текущего пользователя» и что текст под полем «Конфигурация» содержит надпись «Тестировать в режиме
AuthMode.None
Запустите тестовое развертывание и откройте меню «Расширения» .
Если все пункты меню отображаются, проблема устранена. Если вы видите только меню «Справка» , вернитесь к шагу 1. Возможно, вы пропустили вызов службы поддержки.