Аутентификация для пользовательских функций без общей среды выполнения

Статья
02/10/2024

В некоторых сценариях пользовательская функция, которая не использует общую среду выполнения , должна будет пройти проверку подлинности пользователя для доступа к защищенным ресурсам. Пользовательские функции, которые не используют общую среду выполнения, выполняются в среде выполнения, доступной только для JavaScript. По этой причине, если надстройка имеет область задач, необходимо будет передавать данные между средой выполнения только JavaScript и средой выполнения, поддерживающей HTML, используемой областью задач. Для этого используется объект OfficeRuntime.storage и специальный API Dialog.

Важно!

Обратите внимание, что настраиваемые функции доступны в Excel на следующих платформах.

Office в Интернете
Office для Windows
- Подписка на Microsoft 365
- Розничный бессрочный Office 2016 и более поздних версий
- Корпоративный бессрочный Office 2021 и более поздних версий
Office для Mac

Пользовательские функции Excel в настоящее время не поддерживаются в следующих приложениях:

Office для iPad
корпоративные бессрочные версии Office 2019 или более ранних версий в Windows

Примечание.

Мы рекомендуем использовать пользовательские функции с общей средой выполнения, если у вас нет конкретных причин не использовать общую среду выполнения. Обратите внимание, что использование общей среды выполнения означает, что ваша надстройка будет использовать WebView2 (на основе Microsoft Edge Chromium) при соблюдении условий, а в противном случае ваша надстройка будет использовать Trident (Internet Explorer 11) независимо от версии Windows или Microsoft 365. Описание условий WebView2 см. в статье Браузеры и элементы управления webview, используемые надстройками Office. Дополнительные сведения о средах выполнения см. в разделе Среды выполнения в надстройках Office.

Объект OfficeRuntime.storage

В среде выполнения, доступной только для JavaScript, нет объекта, доступного localStorage в глобальном окне, где обычно хранятся данные. Вместо этого код должен совместно использовать данные между пользовательскими функциями и областями задач, используя для OfficeRuntime.storage задания и получения данных.

API диалогового окна

Если маркер не существует, следует использовать OfficeRuntime.dialog API, чтобы попросить пользователя войти в систему. После ввода пользователем своих учетных данных полученный маркер доступа может храниться в виде элемента в OfficeRuntime.storage.

Примечание.

Среда выполнения, доступная только для JavaScript, использует объект dialog, который немного отличается от объекта диалогового окна в среде выполнения браузера, используемой областями задач. Они оба называются "ДИАЛОГОВЫМ API", но используют OfficeRuntime.displayWebDialog для проверки подлинности пользователей в среде выполнения, доступной только для JavaScript, а неOffice.ui.displayDialogAsync.

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

Вы выполняете вызов пользовательской функции из ячейки книги Excel.
Пользовательская функция использует OfficeRuntime.dialog для передачи учетных данных пользователя на веб-сайт.
Затем этот веб-сайт возвращает маркер доступа на страницу в диалоговом окне.
JavaScript в диалоговом окне вызывает функцию Office.ui.messageParent для отправки маркера доступа пользовательской функции. Дополнительные сведения об этой функции см. в разделе Отправка сведений из диалогового окна на хост-страницу.
Затем пользовательская функция задает этот маркер доступа для элемента в OfficeRuntime.storage.
Область задач надстройки получает доступ к маркеру из объекта OfficeRuntime.storage.

Схема пользовательской функции с помощью API диалогового окна для получения маркера доступа, а затем совместного использования маркера с областью задач через API OfficeRuntime.storage.

Хранение маркера

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

При проверке подлинности пользовательской функцией она получает маркер доступа, который должен храниться в объекте OfficeRuntime.storage. В следующем примере кода показано, как вызвать метод storage.setItem чтобы сохранить значение. Функция storeValue является пользовательской функцией, которая хранит значение пользователя. Можно внести изменение, чтобы сохранять любые нужные значения маркеров.

/**
 * Stores a key-value pair into OfficeRuntime.storage.
 * @customfunction
 * @param {string} key Key of item to put into storage.
 * @param {*} value Value of item to put into storage.
 */
function storeValue(key, value) {
  return OfficeRuntime.storage.setItem(key, value).then(function (result) {
      return "Success: Item with key '" + key + "' saved to storage.";
  }, function (error) {
      return "Error: Unable to save item with key '" + key + "' to storage. " + error;
  });
}

Если область задач нуждается в маркере доступа, она может получить маркер из OfficeRuntime.storage элемента. В следующем примере кода показано, как использовать метод storage.getItem чтобы извлечь маркер.

/**
 * Read a token from storage.
 * @customfunction GETTOKEN
 */
function receiveTokenFromCustomFunction() {
  const key = "token";
  const tokenSendStatus = document.getElementById('tokenSendStatus');
  OfficeRuntime.storage.getItem(key).then(function (result) {
     tokenSendStatus.value = "Success: Item with key '" + key + "' read from storage.";
     document.getElementById('tokenTextBox2').value = result;
  }, function (error) {
     tokenSendStatus.value = "Error: Unable to read item with key '" + key + "' from storage. " + error;
  });
}

Общие рекомендации

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

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

localStorage: пользовательские функции, которые не используют общую среду выполнения, не имеют доступа к глобальному window объекту и, следовательно, не имеют доступа к данным, хранящимся в localStorage.
Office.context.document.settings: это расположение небезопасно, и сведения могут быть извлечены любым пользователем надстройки.

Пример API диалогового окна

В следующем примере кода функция getTokenViaDialog использует функцию OfficeRuntime.displayWebDialog для отображения диалогового окна. Этот пример предоставляется для демонстрации возможностей метода, а не для демонстрации проверки подлинности.

/**
 * Function retrieves a cached token or opens a dialog box if there is no saved token. Note that this isn't a sufficient example of authentication but is intended to show the capabilities of the displayWebDialog method.
 * @param {string} url URL for a stored token.
 */
function getTokenViaDialog(url) {
  return new Promise (function (resolve, reject) {
    if (_dialogOpen) {
      // Can only have one dialog box open at once. Wait for previous dialog box's token.
      let timeout = 5;
      let count = 0;
      const intervalId = setInterval(function () {
        count++;
        if(_cachedToken) {
          resolve(_cachedToken);
          clearInterval(intervalId);
        }
        if(count >= timeout) {
          reject("Timeout while waiting for token");
          clearInterval(intervalId);
        }
      }, 1000);
    } else {
      _dialogOpen = true;
      OfficeRuntime.displayWebDialog(url, {
        height: '50%',
        width: '50%',
        onMessage: function (message, dialog) {
          _cachedToken = message;
          resolve(message);
          dialog.close();
          return;
        },
        onRuntimeError: function(error, dialog) {
          reject(error);
        },
      }).catch(function (e) {
        reject(e);
      });
    }
  });
}

Дальнейшие действия

Узнайте, как отлаживать пользовательские функции.

Поделиться через