Authentification pour les fonctions personnalisées sans runtime partagé

Dans certains scénarios, une fonction personnalisée qui n’utilise pas de runtime partagé doit authentifier l’utilisateur pour accéder aux ressources protégées. Les fonctions personnalisées qui n’utilisent pas de runtime partagé s’exécutent dans un runtime JavaScript uniquement. Pour cette raison, si le complément dispose d’un volet Office, vous devez transmettre des données entre le runtime JavaScript uniquement et le runtime html utilisé par le volet Office. Pour ce faire, utilisez l’objet OfficeRuntime.storage et une API de dialogue spéciale.

Importante

Notez que les fonctions personnalisées Excel sont disponibles sur les plateformes suivantes.

• Office sur le web
• Office pour Windows
  • Abonnement Microsoft 365
  • retail perpetual Office 2016 et versions ultérieures
  • avec licence en volume avec licence perpétuelle Office 2021 et versions ultérieures
• Office sur Mac

Les fonctions personnalisées Excel ne sont actuellement pas prises en charge dans les éléments suivants :

• Office sur iPad
• versions perpétuelles avec licence en volume d’Office 2019 ou version antérieure sur Windows

Remarque

Nous vous recommandons d’utiliser des fonctions personnalisées avec un runtime partagé, sauf si vous avez une raison spécifique de ne pas utiliser un runtime partagé. Notez que l’utilisation d’un runtime partagé signifie que votre complément utilisera WebView2 (basé sur Microsoft Edge Chromium) si les conditions sont remplies. Sinon, votre complément utilisera Trident (Internet Explorer 11), quelle que soit la version de Windows ou de Microsoft 365. Pour obtenir une description des conditions WebView2, voir Navigateurs et contrôles webview utilisés par les compléments Office. Pour plus d’informations sur les runtimes, voir Runtimes dans les compléments Office.

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 vérifier OfficeRuntime.storage 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.

API de boîte de dialogue

S’il n’existe pas de jeton, vous devez utiliser l’API OfficeRuntime.dialog 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.

Remarque

Le runtime JavaScript uniquement utilise un objet dialog légèrement différent de l’objet dialog dans le runtime du navigateur utilisé par les volets Office. Elles sont toutes deux appelées « API de dialogue », mais utilisent OfficeRuntime.displayWebDialog pour authentifier les utilisateurs dans le runtime JavaScript uniquement, et nonDans Office.ui.displayDialogAsync.

Le diagramme suivant décrit ce processus de base. La ligne en pointillés indique que les fonctions personnalisées et le volet Office de votre complément font tous deux partie de votre complément dans son ensemble, bien qu’ils utilisent des runtimes distincts.

1. Vous émettez un appel de fonction personnalisée à partir d’une cellule d’un classeur Excel.
2. La fonction personnalisée utilise OfficeRuntime.dialog pour transmettre vos informations d’identification d’utilisateur à un site Web.
3. Ce site web retourne ensuite un jeton d’accès à la page dans la boîte de dialogue.
4. Votre code JavaScript dans la boîte de dialogue appelle la fonction Office.ui.messageParent pour envoyer le jeton d’accès à la fonction personnalisée. Pour plus d’informations sur cette fonction, consultez Envoyer des informations de la boîte de dialogue à la page hôte.
5. Votre fonction personnalisée définit ensuite ce jeton d’accès sur un élément dans .OfficeRuntime.storage
6. Le volet de tâches de votre complément accède au jeton à partir deOfficeRuntime.storage.

Stockage du jeton

Les exemples suivants s’appliquent à partir de l’exemple de codeutilisation d’OfficeRuntime.storage dans les fonctions personnalisées. Reportez-vous à cet exemple de code pour obtenir un exemple complet de partage de données entre des fonctions personnalisées et le volet Office dans les compléments qui n’utilisent pas de runtime partagé.

Si la fonction personnalisée s’authentifie, elle reçoit le jeton d’accès et doit la stocker dans OfficeRuntime.storage. L’exemple de code suivant montre comment appeler la méthodestorage.setItem pour stocker une valeur. La storeValue fonction est une fonction personnalisée qui stocke une valeur de l’utilisateur. Vous pouvez modifier cette valeur pour stocker les valeurs 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 sont basés sur le Web et vous pouvez utiliser n’importe quelle technique d’authentification Web. Il n’existe pas de modèle ou de méthode spécifique que vous devez suivre pour implémenter votre propre authentification avec des fonctions personnalisées. Vous pouvez consulter la documentation relative à différents modèles d’authentification, en commençant parcet article sur l’autorisation d’accès via les services externes.

É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 les informations peuvent être extraites par toute personne utilisant le complément.

Exemple d’API de boîte de dialogue

Dans l’exemple de code suivant, la fonction getTokenViaDialog utilise la OfficeRuntime.displayWebDialog fonction pour afficher une boîte de dialogue. Cet exemple est fourni pour montrer les fonctionnalités de la méthode, et non pour montrer comment s’authentifier.

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

É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