Эта страница переведена с помощью Cloud Translation API.

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

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

Модель авторизации надстроек редактора более сложная. Поскольку эти надстройки работают с файлами, хранящимися на Google Диске — файлами, которыми можно поделиться с другими, — вы должны создавать надстройки редактора с учетом различных режимов авторизации . Редакторы Google Docs также предоставляют меню надстроек в своих пользовательских интерфейсах, которое заполняется установленными вами надстройками, даже если вы еще не авторизовали эти надстройки. Это усложняет модель авторизации.

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

Два свойства надстроек редактора делают их особенно удобными для совместного использования и использования:

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

Эта модель обмена кажется естественной для большинства пользователей. Однако, поскольку надстройка редактора автоматически запускает функцию onOpen(e) для добавления элементов меню при открытии редактора Документов Google, описанное выше поведение усложняет правила авторизации в Apps Script. В конце концов, пользователям будет неудобно, если надстройка будет получать доступ к личным данным каждый раз, когда они открывают документ, форму, презентацию или электронную таблицу. Это руководство должно помочь вам понять, что и когда может делать ваш код.

Установлено против включено

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

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

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

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

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

В частности, установленное и включенное состояния определяют, в каком режиме авторизации работает функция onOpen(e) . Сценарий приложений передает режим авторизации как свойство authMode параметра события сценария приложений e ; значение e.authMode соответствует константе в перечислении Apps ScriptApp.AuthMode .

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

Концепция режимов авторизации применяется ко всем исполнениям скрипта приложений, например запуску из редактора скриптов, из пункта меню или из вызова google.script.run скрипта приложений, хотя свойство e.authMode можно проверить только в том случае, если скрипт запускается в результате триггера , такого как onOpen(e) , onEdit(e) или onInstall(e) . Пользовательские функции в Google Таблицах используют собственный режим авторизации AuthMode.CUSTOM_FUNCTION , который похож на LIMITED , но имеет немного другие ограничения. В остальное время сценарии выполняются в AuthMode.FULL , как указано в таблице ниже.

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

Полный жизненный цикл

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

Установка

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

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

Открытие

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

Если надстройка создает только базовое меню, режим не имеет значения. В этом примере показано, как может выглядеть простой onOpen(e) :

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

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

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(e) загружается весь скрипт и выполняются все глобальные операторы. Эти операторы выполняются в том же режиме авторизации, что и onOpen(e) , и терпят неудачу, если режим их запрещает. Это предотвращает запуск onOpen(e) . Если в опубликованном дополнении не удается добавить пункты меню, посмотрите в консоли JavaScript браузера, не возникла ли ошибка, а затем проверьте свой сценарий, чтобы узнать, вызывает ли функция onOpen(e) или глобальные переменные сервисы, которые не разрешены. в AuthMode.NONE .

Бег

Когда кто-то щелкает один из пунктов меню надстройки, Apps Script сначала проверяет, установил ли пользователь надстройку, и предлагает сделать это, если нет. Если пользователь авторизовал надстройку, скрипт запускает функцию, соответствующую пункту меню в AuthMode.FULL . Надстройка также становится доступной в документе, форме, презентации или электронной таблице, если она еще не включена.