Freigeben über

Authentifizierung für benutzerdefinierte Funktionen ohne gemeinsame Laufzeit

  • Artikel

In einigen Szenarien muss eine benutzerdefinierte Funktion, die keine freigegebene Runtime verwendet, den Benutzer authentifizieren, um auf geschützte Ressourcen zugreifen zu können. Benutzerdefinierte Funktionen, die keine freigegebene Runtime verwenden, werden in einer reinen JavaScript-Runtime ausgeführt. Wenn das Add-In über einen Aufgabenbereich verfügt, müssen Sie daher Daten zwischen der reinen JavaScript-Runtime und der HTML-unterstützenden Runtime, die vom Aufgabenbereich verwendet wird, hin- und her übergeben. Dazu verwenden Sie das OfficeRuntime.storage-Objekt und eine spezielle Dialog-API.

Wichtig

Beachten Sie, dass benutzerdefinierte Excel-Funktionen auf den folgenden Plattformen verfügbar sind.

  • Office im Web
  • Office unter Windows
    • Microsoft 365-Abonnement
    • retail unbefristete Office 2016 und höher
    • volumenlizenziertes unbefristetes Office 2021 und höher
  • Office für Mac

Benutzerdefinierte Excel-Funktionen werden derzeit in den folgenden Artikeln nicht unterstützt:

  • Office auf dem iPad
  • Volumenlizenzierte unbefristete Versionen von Office 2019 oder früher unter Windows

Hinweis

Es wird empfohlen, benutzerdefinierte Funktionen mit einer freigegebenen Runtime zu verwenden, es sei denn, Sie haben einen bestimmten Grund, eine freigegebene Runtime nicht zu verwenden. Beachten Sie, dass die Verwendung einer freigegebenen Runtime bedeutet, dass Ihr Add-In WebView2 (Microsoft Edge Chromium-basiert) verwendet, wenn Bedingungen erfüllt sind. Andernfalls verwendet Ihr Add-In Trident (Internet Explorer 11) unabhängig von der Windows- oder Microsoft 365-Version. Eine Beschreibung der WebView2-Bedingungen finden Sie unter Browser und Webview-Steuerelemente, die von Office-Add-Ins verwendet werden. Weitere Informationen zu Runtimes finden Sie unter Runtimes in Office-Add-Ins.

OfficeRuntime.storage-Objekt

Die reine JavaScript-Runtime verfügt nicht über ein localStorage Objekt im globalen Fenster, in dem Sie normalerweise Daten speichern. Stattdessen sollte Ihr Code Daten zwischen benutzerdefinierten Funktionen und Aufgabenbereichen freigeben, indem zum Festlegen und Abrufen von Daten verwendet OfficeRuntime.storage wird.

Vorgeschlagene Verwendung

Wenn Sie sich über ein benutzerdefiniertes Funktions-Add-In authentifizieren müssen, das keine freigegebene Runtime verwendet, sollte Ihr Code überprüfen OfficeRuntime.storage , ob das Zugriffstoken bereits abgerufen wurde. Wenn dies nicht der Fehler ist, verwenden Sie OfficeRuntime.displayWebDialog , um den Benutzer zu authentifizieren, das Zugriffstoken abzurufen und das Token dann zur zukünftigen Verwendung in OfficeRuntime.storage zu speichern.

Dialog-API

Wenn kein Token vorhanden ist, sollten Sie die OfficeRuntime.dialog API verwenden, um den Benutzer aufzufordern, sich anzumelden. Nachdem ein Benutzer seine Anmeldeinformationen eingegeben hat, kann das resultierende Zugriffstoken als Element in OfficeRuntime.storagegespeichert werden.

Hinweis

Die reine JavaScript-Runtime verwendet ein Dialogobjekt, das sich geringfügig vom Dialogobjekt in der Browserlaufzeit unterscheidet, die von Aufgabenbereichen verwendet wird. Beide werden als "Dialog-API" bezeichnet, verwenden jedoch OfficeRuntime.displayWebDialog , um Benutzer in der reinen JavaScript-Runtime zu authentifizieren, nichtoffice.ui.displayDialogAsync.

Das folgende Diagramm beschreibt diesen grundlegenden Vorgang. Die gepunktete Linie gibt an, dass benutzerdefinierte Funktionen und der Aufgabenbereich Ihres Add-Ins beide Teil Ihres Add-Ins als Ganzes sind, obwohl sie separate Laufzeiten verwenden.

  1. Sie rufen eine benutzerdefinierte Funktionsaufruf aus einer Zelle in einer Excel-Arbeitsmappe auf.
  2. Die benutzerdefinierte Funktion verwendet OfficeRuntime.dialog, um Ihre Benutzeranmeldeinformationen an eine Website zu übergeben.
  3. Diese Website gibt dann ein Zugriffstoken für die Seite im Dialogfeld zurück.
  4. Ihr JavaScript im Dialogfeld ruft die Office.ui.messageParent-Funktion auf, um das Zugriffstoken an die benutzerdefinierte Funktion zu senden. Weitere Informationen zu dieser Funktion finden Sie unter Senden von Informationen aus dem Dialogfeld an die Hostseite.
  5. Ihre benutzerdefinierte Funktion legt dieses Zugriffstoken dann auf ein Element im OfficeRuntime.storagefest.
  6. Der Aufgabenbereich des Add-Ins greift aus OfficeRuntime.storage auf das Token zu.

Diagramm der benutzerdefinierten Funktion, die die Dialog-API zum Abrufen des Zugriffstokens und anschließendes Freigeben des Tokens für den Aufgabenbereich über die OfficeRuntime.storage-API verwendet.

Speichern des Tokens

Die folgenden Beispiele stammen aus dem Codebeispiel Verwenden von OfficeRuntime.storage in benutzerdefinierten Funktionen. In diesem Codebeispiel finden Sie ein vollständiges Beispiel für die Freigabe von Daten zwischen benutzerdefinierten Funktionen und dem Aufgabenbereich in Add-Ins, die keine freigegebene Runtime verwenden.

Bei der Authentifizierung der benutzerdefinierten Funktion empfängt sie das Zugriffstoken und muss es in OfficeRuntime.storage speichern. Im folgenden Codebeispiel wird veranschaulicht, wie die storage.setItem-Methode zum Speichern eines Werts aufgerufen wird. Die storeValue Funktion ist eine benutzerdefinierte Funktion, die einen Wert vom Benutzer speichert. Sie können dies so ändern, dass Sie beliebige benötigte Tokenwerte gespeichert werden.

/**
 * 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;
  });
}

Wenn der Aufgabenbereich das Zugriffstoken benötigt, kann er das Token aus dem OfficeRuntime.storage Element abrufen. Im folgenden Codebeispiel wird veranschaulicht, wie die storage.getItem-Methode verwendet wird, um ein Token abzurufen.

/**
 * 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;
  });
}

Allgemeine Hinweise

Office-Add-Ins sind webbasiert, und Sie können jedes beliebige Webauthentifizierungsverfahren verwenden. Es gibt keine bestimmten Muster oder Methoden, die Sie zum Implementieren ihrer eigenen Authentifizierung für benutzerdefinierte Funktionen verwenden müssen. In der Dokumentation können Sie sich über verschiedene Authentifizierungsmuster informieren, beispielsweise, indem Sie mit diesem Artikel über die Autorisierung über externe Dienste beginnen.

Vermeiden Sie beim Entwickeln von benutzerdefinierten Funktionen, die folgenden Speicherorte zum Speichern von Daten zu verwenden:

  • localStorage: Benutzerdefinierte Funktionen, die keine freigegebene Runtime verwenden, haben keinen Zugriff auf das globale window Objekt und daher keinen Zugriff auf in gespeicherte localStorageDaten.
  • Office.context.document.settings: Dieser Speicherort ist nicht sicher, und Die Informationen können von jeder Person extrahiert werden, die das Add-In verwendet.

Beispiel für die Dialogfeld-API

Im folgenden Codebeispiel verwendet die Funktion getTokenViaDialog die OfficeRuntime.displayWebDialog -Funktion, um ein Dialogfeld anzuzeigen. Dieses Beispiel wird bereitgestellt, um die Funktionen der -Methode zu veranschaulichen und nicht die Authentifizierung zu veranschaulichen.

/**
 * 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);
      });
    }
  });
}

Nächste Schritte

Erfahren Sie, wie Sie benutzerdefinierte Funktionen debuggen.

Siehe auch