Authentification pour les fonctions personnalisées sans runtime partagé

Si votre fonction personnalisée Excel n’utilise pas de runtime partagé, elle s’exécute dans un runtime JavaScript uniquement. Dans ce runtime, l’authentification nécessite généralement un flux de dialogue et un partage de jetons avec votre volet Office.

Utilisez OfficeRuntime.displayWebDialog pour vous connecter et OfficeRuntime.storage pour mettre en cache et partager le jeton entre les runtimes.

Flux de travail d’authentification

Le flux de travail suivant est classique pour les fonctions personnalisées qui n’utilisent pas de runtime partagé.

1. Un utilisateur exécute une fonction personnalisée dans une cellule Excel.
2. La fonction personnalisée appelle OfficeRuntime.displayWebDialog pour ouvrir une page de connexion dans une boîte de dialogue, où l’utilisateur entre ses informations d’identification.
3. La page de connexion retourne un jeton d’accès à la boîte de dialogue.
4. La boîte de dialogue appelle Office.ui.messageParent pour envoyer le jeton d’accès à la fonction personnalisée. Pour plus d’informations, consultez Envoyer des informations de la boîte de dialogue à la page hôte.
5. La fonction personnalisée stocke le jeton d’accès dans OfficeRuntime.storage.
6. Le volet Office du complément obtient le jeton à partir de OfficeRuntime.storage.

Essayez-le avec un exemple

Utilisez l’exemple Utilisation d’OfficeRuntime.storage dans les fonctions personnalisées pour tester le stockage de jetons et la récupération entre des fonctions personnalisées et un volet Office.

API de boîte de dialogue

S’il n’existe pas de jeton, vous devez utiliser OfficeRuntime.displayWebDialog pour demander à l’utilisateur de se connecter. Une fois qu’un utilisateur a entré ses informations d’identification, le jeton d’accès résultant peut être stocké en tant qu’élément dans OfficeRuntime.storage.

Exemple d’API de boîte de dialogue

Dans l’exemple de code suivant, getTokenViaDialog utilise OfficeRuntime.displayWebDialog pour afficher une boîte de dialogue. Cet exemple montre les fonctionnalités de méthode et n’est pas une implémentation d’authentification complète.

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

Objet OfficeRuntime.storage

Le runtime JavaScript uniquement n’a pas d’objet localStorage disponible dans la fenêtre globale, où vous stockez généralement des données. Au lieu de cela, votre code doit partager des données entre des fonctions personnalisées et des volets office en utilisant OfficeRuntime.storage pour définir et obtenir des données.

Utilisation suggérée

Lorsque vous devez vous authentifier à partir d’un complément de fonction personnalisé qui n’utilise pas de runtime partagé, votre code doit case activée OfficeRuntime.storage pour voir si le jeton d’accès a déjà été acquis. Si ce n’est pas le cas, utilisez OfficeRuntime.displayWebDialog pour authentifier l’utilisateur, récupérer le jeton d’accès, puis stocker le jeton dans OfficeRuntime.storage pour une utilisation ultérieure.

Stockage du jeton

Les exemples suivants montrent comment stocker et récupérer des jetons à l’aide OfficeRuntime.storagede .

Si la fonction personnalisée s’authentifie, elle reçoit un jeton d’accès qu’elle doit stocker dans OfficeRuntime.storage. L’exemple de code suivant montre comment appeler storage.setItem pour stocker une valeur. La storeValue fonction est une fonction personnalisée qui stocke une valeur de l’utilisateur. Vous pouvez le modifier pour stocker n’importe quelle valeur de jeton dont vous avez besoin.

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

Lorsque le volet Office a besoin du jeton d’accès, il peut récupérer le jeton à partir de l’élément OfficeRuntime.storage . L’exemple de code suivant montre comment utiliser la méthodestorage.getItem pour récupérer le jeton.

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

Instructions générales

Les compléments Office étant basés sur le web, vous pouvez utiliser n’importe quelle technique d’authentification web. Il n’existe pas de modèle d’authentification requis pour les fonctions personnalisées. Commencez par Autoriser les services externes dans les compléments Office pour les modèles de conception et les compromis.

Évitez d’utiliser les emplacements suivants pour stocker des données lors du développement de fonctions personnalisées :

• localStorage: les fonctions personnalisées qui n’utilisent pas de runtime partagé n’ont pas accès à l’objet global window et n’ont donc pas accès aux données stockées dans localStorage.
• Office.context.document.settings: cet emplacement n’est pas sécurisé et toute personne utilisant le complément peut extraire ces informations.

Étapes suivantes

Découvrez comment déboguer des fonctions personnalisées.

Voir aussi

• Runtime JavaScript uniquement pour les fonctions personnalisées
• Didacticiel de fonctions personnalisées Excel
• Runtime JavaScript uniquement