Autenticación para funciones personalizadas sin un entorno de ejecución compartido

Si la función personalizada de Excel no usa un entorno de ejecución compartido, se ejecuta en un entorno de ejecución de solo JavaScript. En ese entorno de ejecución, la autenticación normalmente requiere un flujo de diálogo y un uso compartido de tokens con el panel de tareas.

Use OfficeRuntime.displayWebDialog para iniciar sesión y OfficeRuntime.storage para almacenar en caché y compartir el token entre entornos de ejecución.

Flujo de trabajo de autenticación

El siguiente flujo de trabajo es típico de las funciones personalizadas que no usan un entorno de ejecución compartido.

1. Un usuario ejecuta una función personalizada en una celda de Excel.
2. La función personalizada llama OfficeRuntime.displayWebDialog a para abrir una página de inicio de sesión en un cuadro de diálogo, donde el usuario escribe sus credenciales.
3. La página de inicio de sesión devuelve un token de acceso al cuadro de diálogo.
4. El cuadro de diálogo llama a Office.ui.messageParent para enviar el token de acceso a la función personalizada. Para obtener más información, vea Enviar información desde el cuadro de diálogo a la página host.
5. La función personalizada almacena el token de acceso en OfficeRuntime.storage.
6. El panel de tareas del complemento obtiene el token de OfficeRuntime.storage.

Pruébelo con un ejemplo

Use el ejemplo Uso de OfficeRuntime.storage en funciones personalizadas para probar el almacenamiento de tokens y la recuperación entre funciones personalizadas y un panel de tareas.

API de diálogo

Si no existe un token, debe usar OfficeRuntime.displayWebDialog para pedir al usuario que inicie sesión. Una vez que un usuario escribe sus credenciales, el token de acceso resultante se puede almacenar como un elemento en OfficeRuntime.storage.

Ejemplo de API de cuadro de diálogo

En el ejemplo de código siguiente, getTokenViaDialog usa OfficeRuntime.displayWebDialog para mostrar un cuadro de diálogo. En este ejemplo se muestran las funcionalidades del método y no es una implementación de autenticación completa.

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

Objeto OfficeRuntime.storage

El entorno de ejecución solo JavaScript no tiene un localStorage objeto disponible en la ventana global, donde normalmente se almacenan datos. En su lugar, el código debe compartir datos entre funciones personalizadas y paneles de tareas mediante OfficeRuntime.storage para establecer y obtener datos.

Uso sugerido

Cuando necesite autenticarse desde un complemento de función personalizada que no use un entorno de ejecución compartido, el código debe comprobar OfficeRuntime.storage si el token de acceso ya se ha adquirido. Si no es así, use OfficeRuntime.displayWebDialog para autenticar al usuario, recuperar el token de acceso y, a continuación, almacenar el token en OfficeRuntime.storage para su uso futuro.

Almacenar el token

En los ejemplos siguientes se muestra cómo almacenar y recuperar tokens mediante OfficeRuntime.storage.

Si la función personalizada se autentica, recibe un token de acceso que debe almacenar en OfficeRuntime.storage. En el ejemplo de código siguiente se muestra cómo llamar storage.setItem a para almacenar un valor. La storeValue función es una función personalizada que almacena un valor del usuario. Puede modificarlo para almacenar cualquier valor de token que necesite.

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

Cuando el panel de tareas necesita el token de acceso, puede recuperar el token del OfficeRuntime.storage elemento. El siguiente código de ejemplo muestra cómo llamar al método storage.getItem para recuperar el token.

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

Instrucciones generales

Los complementos de Office se basan en web, por lo que puede usar cualquier técnica de autenticación web. No hay un patrón de autenticación necesario para las funciones personalizadas. Comience con Autorizar a servicios externos en complementos de Office para patrones de diseño y compensaciones.

Evite usar las siguientes ubicaciones para almacenar datos al desarrollar funciones personalizadas:

• localStorage: las funciones personalizadas que no usan un entorno de ejecución compartido no tienen acceso al objeto global window y, por tanto, no tienen acceso a los datos almacenados en localStorage.
• Office.context.document.settings: esta ubicación no es segura y cualquiera que use el complemento puede extraer esta información.

Pasos siguientes

Obtenga información sobre cómo depurar funciones personalizadas.

Vea también

• Tiempo de ejecución solo de JavaScript para funciones personalizadas
• Tutorial de las funciones personalizadas de Excel
• Tiempo de ejecución de solo JavaScript