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

Em alguns cenários, uma função personalizada que não usa um runtime compartilhado precisará autenticar o usuário para acessar recursos protegidos. Funções personalizadas que não usam uma execução de runtime compartilhado em um runtime somente JavaScript. Por causa disso, se o suplemento tiver um painel de tarefas, você precisará passar dados para frente e para trás entre o runtime somente JavaScript e o runtime de suporte html usado pelo painel de tarefas. Você faz isso usando o objeto OfficeRuntime.storage e uma API de Diálogo especial.

Importante

Observe que as funções personalizadas do Excel estão disponíveis nas plataformas a seguir.

• Office na Web
• Office no Windows
  • Assinatura do Microsoft 365
  • varejo perpétuo Office 2016 e posterior
  • Office 2021 perpétuo licenciado por volume e posterior
• Office no Mac

No momento, as funções personalizadas do Excel não têm suporte no seguinte:

• Office no iPad
• versões perpétuas licenciadas por volume do Office 2019 ou anteriores no Windows

Observação

Recomendamos usar funções personalizadas com um runtime compartilhado, a menos que você tenha um motivo específico para não usar um runtime compartilhado. Observe que o uso de um runtime compartilhado significa que seu suplemento usará o WebView2 (baseado em Chromium do Microsoft Edge) se as condições forem atendidas e, caso contrário, seu suplemento usará Trident (Internet Explorer 11), independentemente da versão do Windows ou do Microsoft 365. Para obter uma descrição das condições do WebView2, consulte Navegadores e controles de visão da Web usados pelos Suplementos do Office. Para obter mais informações sobre runtimes, consulte Runtimes em Suplementos do Office e Runtimes.

Objeto OfficeRuntime.storage

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

Uso sugerido

Quando você precisa se autenticar de um suplemento de função personalizado que não usa um runtime compartilhado, seu código deve marcar OfficeRuntime.storage para ver 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.

API de caixa de diálogo

Se um token não existir, você deverá usar a OfficeRuntime.dialog API para pedir ao usuário para entrar. Depois que um usuário insere suas credenciais, o token de acesso resultante pode ser armazenado como um item no OfficeRuntime.storage.

Observação

O runtime somente JavaScript usa um objeto de diálogo ligeiramente diferente do objeto de caixa de diálogo no runtime do navegador usado pelos painéis de tarefa. Ambos são chamados de "API de Diálogo", mas usam OfficeRuntime.displayWebDialog para autenticar usuários no runtime somente JavaScript, nãoOffice.ui.displayDialogAsync.

O diagrama a seguir descreve esse processo básico. A linha pontilhada indica que as funções personalizadas e o painel de tarefas do suplemento fazem parte do suplemento como um todo, embora usem runtimes separados.

1. As chamadas de função personalizada de uma célula são emitdas por você em uma pasta de trabalho do Excel.
2. A função personalizada usa OfficeRuntime.dialog para passar suas credenciais de usuário para um site.
3. Em seguida, este site retorna um token de acesso à página na caixa de diálogo.
4. Seu JavaScript na caixa de diálogo chama a função Office.ui.messageParent para enviar o token de acesso à função personalizada. Para obter mais informações sobre essa função, consulte Enviar informações da caixa de diálogo para a página do host.
5. Sua função personalizada define esse token de acesso como um item no OfficeRuntime.storage.
6. O painel de tarefas do seu suplemento acessa o token a partir de OfficeRuntime.storage.

Armazenando o token

Os exemplos a seguir são do exemplo de código Usando OfficeRuntime.storage em funções personalizadas. Consulte este exemplo de código para obter um exemplo completo de compartilhamento de dados entre funções personalizadas e o painel de tarefas em suplementos que não usam um runtime compartilhado.

Se a função personalizada for autenticada, ela receberá o token de acesso e precisará armazená-lo em OfficeRuntime.storage. O exemplo de código a seguir mostra como chamar o método storage.setItem para armazenar um valor. A storeValue função é uma função personalizada que armazena um valor do usuário. Você pode modificá-la para que seja armazenado qualquer valor de token que você precise.

/**
 * 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 precisa do token de acesso, ele pode recuperar o token do OfficeRuntime.storage 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 e você pode usar qualquer técnica de autenticação da Web. Não há um padrão ou método específico que você deva seguir para implementar sua própria autenticação com funções personalizadas. Você pode querer consultar a documentação sobre vários padrões de autenticação, começando com este artigo sobre a autorização por serviços externos.

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 as informações podem ser extraídas por qualquer pessoa que use o suplemento.

Exemplo de API da caixa de diálogo

No exemplo de código a seguir, a função getTokenViaDialog usa a OfficeRuntime.displayWebDialog função para exibir uma caixa de diálogo. Este exemplo é fornecido para mostrar as funcionalidades do método, não demonstrar como autenticar.

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

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