Autenticação para funções personalizadas sem um tempo de execução compartilhado

Se a função personalizada do Excel não usar um runtime compartilhado, ela será executada em um runtime somente JavaScript. Nesse tempo de execução, a autenticação geralmente requer um fluxo de caixas de diálogo e compartilhamento de token com seu painel de tarefas.

Use OfficeRuntime.displayWebDialog para entrar e OfficeRuntime.storage para armazenar em cache e compartilhar o token entre runtimes.

Fluxo de trabalho de autenticação

O fluxo de trabalho a seguir é típico para funções personalizadas que não usam um runtime compartilhado.

1. Um usuário executa uma função personalizada em uma célula do Excel.
2. A função personalizada chama OfficeRuntime.displayWebDialog para abrir uma página de entrada em uma caixa de diálogo, onde o usuário insere suas credenciais.
3. A página de entrada retorna um token de acesso para a caixa de diálogo.
4. A caixa de diálogo chama Office.ui.messageParent para enviar o token de acesso para a função personalizada. Para obter mais informações, consulte Enviar informações da caixa de diálogo para a página do host.
5. A função personalizada armazena o token de acesso no OfficeRuntime.storage.
6. O painel de tarefas do suplemento obtém o token de OfficeRuntime.storage.

Experimente com uma amostra

Use o exemplo Usando OfficeRuntime.storage em funções personalizadas para testar o armazenamento e a recuperação de token entre funções personalizadas e um painel de tarefas.

API de caixa de diálogo

Se um token não existir, você deverá usá-lo OfficeRuntime.displayWebDialog para solicitar que o usuário entre. Depois que um usuário insere suas credenciais, o token de acesso resultante pode ser armazenado como um item no OfficeRuntime.storage.

Exemplo de API de caixa de diálogo

No exemplo de código a seguir, getTokenViaDialog usa OfficeRuntime.displayWebDialog para exibir uma caixa de diálogo. Este exemplo mostra os recursos do método e não é uma implementação de autenticação 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

O runtime somente JavaScript não tem um localStorage objeto disponível na janela global, onde você normalmente armazena dados. Em vez disso, seu código deve compartilhar dados entre funções personalizadas e painéis de tarefas usando OfficeRuntime.storage para definir e obter dados.

Uso sugerido

Quando você precisar se autenticar de um suplemento de função personalizado que não usa um runtime compartilhado, seu código deverá marcar OfficeRuntime.storage se o token de acesso já foi adquirido. Caso contrário, use OfficeRuntime.displayWebDialog para autenticar o usuário, recuperar o token de acesso e armazenar o token para OfficeRuntime.storage uso futuro.

Armazenando o token

Os exemplos a seguir mostram como armazenar e recuperar tokens usando OfficeRuntime.storageo .

Se a função personalizada for autenticada, ela receberá um token de acesso que deverá armazenar no OfficeRuntime.storage. O exemplo de código a seguir mostra como chamar storage.setItem para armazenar um valor. A storeValue função é uma função personalizada que armazena um valor do usuário. Você pode modificá-lo para armazenar qualquer valor de token necessário.

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

Quando o painel de tarefas precisar do token de acesso, ele poderá recuperar o OfficeRuntime.storage token do item. O exemplo de código a seguir mostra como usar o método storage.getItem para recuperar o 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;
  });
}

Orientação geral

Os suplementos do Office são baseados na Web, portanto, você pode usar qualquer técnica de autenticação da Web. Não há um padrão de autenticação obrigatório para funções personalizadas. Comece com Autorizar para serviços externos em Suplementos do Office para padrões de design e compensações.

Evite usar os seguintes locais para armazenar dados ao desenvolver funções personalizadas:

• localStorage: As funções personalizadas que não usam um runtime compartilhado não têm acesso ao objeto global window e, portanto, não têm acesso aos dados armazenados no localStorage.
• Office.context.document.settings: esse local não é seguro e qualquer pessoa que use o suplemento pode extrair essas informações.

Próximas etapas

Saiba como depurar funções personalizadas.

Confira também

• Tempo de execução somente de JavaScript para funções personalizadas
• Tutorial de funções personalizadas do Excel
• Runtime somente JavaScript