Authentifizierung für benutzerdefinierte Funktionen ohne gemeinsame Laufzeit

Wenn Ihre benutzerdefinierte Excel-Funktion keine freigegebene Runtime verwendet, wird sie in einer reinen JavaScript-Runtime ausgeführt. In dieser Laufzeit erfordert die Authentifizierung in der Regel einen Dialogflow und eine Tokenfreigabe für Ihren Aufgabenbereich.

Verwenden Sie OfficeRuntime.displayWebDialog , um sich anzumelden, und OfficeRuntime.storage , um das Token zwischenzuspeichern und zwischen Runtimes freizugeben.

Authentifizierungsworkflow

Der folgende Workflow ist typisch für benutzerdefinierte Funktionen, die keine freigegebene Runtime verwenden.

1. Ein Benutzer führt eine benutzerdefinierte Funktion in einer Excel-Zelle aus.
2. Die benutzerdefinierte Funktion ruft auf OfficeRuntime.displayWebDialog , um eine Anmeldeseite in einem Dialogfeld zu öffnen, auf der der Benutzer seine Anmeldeinformationen eingibt.
3. Die Anmeldeseite gibt ein Zugriffstoken an das Dialogfeld zurück.
4. Das Dialogfeld ruft Office.ui.messageParent auf, um das Zugriffstoken an die benutzerdefinierte Funktion zu senden. Weitere Informationen finden Sie unter Senden von Informationen aus dem Dialogfeld an die Hostseite.
5. Die benutzerdefinierte Funktion speichert das Zugriffstoken in OfficeRuntime.storage.
6. Der Aufgabenbereich des Add-Ins ruft das Token von ab OfficeRuntime.storage.

Probieren Sie es mit einem Beispiel aus

Verwenden Sie das Beispiel Verwenden von OfficeRuntime.storage in benutzerdefinierten Funktionen , um das Speichern und Abrufen von Token zwischen benutzerdefinierten Funktionen und einem Aufgabenbereich zu testen.

Dialog-API

Wenn kein Token vorhanden ist, sollten Sie verwenden OfficeRuntime.displayWebDialog , um den Benutzer zur Anmeldung aufzufordern. Nachdem ein Benutzer seine Anmeldeinformationen eingegeben hat, kann das resultierende Zugriffstoken als Element in OfficeRuntime.storagegespeichert werden.

Beispiel für die Dialogfeld-API

Im folgenden Codebeispiel wird verwendetOfficeRuntime.displayWebDialog, getTokenViaDialog um ein Dialogfeld anzuzeigen. Dieses Beispiel zeigt Methodenfunktionen und ist keine vollständige Authentifizierungsimplementierung.

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

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.

Speichern des Tokens

Die folgenden Beispiele zeigen, wie Token mithilfe OfficeRuntime.storagevon gespeichert und abgerufen werden.

Wenn sich die benutzerdefinierte Funktion authentifiziert, empfängt sie ein Zugriffstoken, das in OfficeRuntime.storagegespeichert werden muss. Im folgenden Codebeispiel wird gezeigt, wie Sie aufrufen storage.setItem , um einen Wert zu speichern. Die storeValue Funktion ist eine benutzerdefinierte Funktion, die einen Wert vom Benutzer speichert. Sie können es ändern, um einen beliebigen Tokenwert zu speichern, den Sie benötigen.

/**
 * 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, sodass Sie jede Webauthentifizierungsmethode verwenden können. Es gibt kein erforderliches Authentifizierungsmuster für benutzerdefinierte Funktionen. Beginnen Sie mit Autorisieren für externe Dienste in Office-Add-Ins , um Entwurfsmuster und Kompromisse zu ermitteln.

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 jeder, der das Add-In verwendet, kann diese Informationen extrahieren.

Nächste Schritte

Erfahren Sie, wie Sie benutzerdefinierte Funktionen debuggen.

Siehe auch

• Reine JavaScript-Laufzeit für benutzerdefinierte Funktionen
• Lernprogramm zum Erstellen von benutzerdefinierten Funktionen in Excel
• Reine JavaScript-Runtime