Exercício – Criar um suplemento do Office para Excel que implemente o logon único
Neste exercício, você criará um suplemento do Excel que adiciona uma lista dos emails recentes recebidos pelo usuário conectado no momento com Microsoft Graph em uma planilha. Esse processo usa o esquema de autenticação de SSO (logon único).
Pré-requisitos
O desenvolvimento de Suplementos do Office para o Microsoft Word requer o cliente Web ou os seguintes clientes da área de trabalho:
- Windows v16.0.12215.20006 ( ou superior )
- macOS v16.32.19102902 ( ou superior )
Você usará o Node.js para criar o suplemento personalizado do Word neste módulo. Os exercícios neste módulo presumem que você tenha as seguintes ferramentas instaladas em sua estação de trabalho de desenvolvedor:
Importante
Na maioria dos casos, instalar a versão mais recente das ferramentas a seguir é a melhor opção. As versões listadas aqui foram usadas quando este módulo foi publicado e testado pela última vez.
- Node.js: (a versãomais recente do LTS)
- NPM (instalado com Node.js) – v6.x (ou superior)
- Yeoman - v3.x (ou superior)
- Gerador yeoman para Microsoft Office - v1.8.8
- Visual Studio Code
Você deve ter as versões mínimas desses pré-requisitos instaladas em sua estação de trabalho.
Importante
Este exercício é escrito para trabalhar com o Gerador yeoman para o Microsoft Office v1.8.8. Verifique se você está usando essa versão instalando uma versão específica usando o comando npm install generator-office@1.8.8 --global. Versões posteriores do gerador foram removidas e, em seguida, alteraram os scaffolding do projeto SSO que não correspondem às etapas neste laboratório.
Importante
O exemplo neste exercício destina-se a ser usado apenas como um recurso de aprendizado e não se destina a ser usado em um cenário de produção porque passa o token OAuth usado para enviar solicitações ao Microsoft Graph de volta ao cliente para fazer a chamada diretamente.
Como prática de segurança, sempre use o código ao lado do servidor para fazer chamadas pelo Microsoft Graph ou outras chamadas que exigem a passagem de um token de acesso. Nunca retorne o token OBO ao cliente para permitir que o cliente faça chamadas diretas ao Microsoft Graph. Isso ajuda a proteger o token de ser interceptado ou vazado. Para obter mais informações sobre o fluxo de protocolo adequado, consulte o diagrama de protocolo OAuth 2.0.
Criar seu projeto do suplemento
Execute o seguinte comando para criar um projeto de suplemento usando o gerador Yeoman:
yo office
Observação
Ao executar o comando yo office, você receberá informações sobre as políticas de coleta de dados de Yeoman e as ferramentas da CLI do suplemento do Office. Use as informações fornecidas para responder às solicitações como achar melhor.
Quando solicitado, forneça as seguintes informações para criar seu projeto de suplemento:
- Selecione um tipo de projeto: projeto do painel de tarefas do suplemento do Office com suporte para logon único
- Selecione um tipo de script: JavaScript
- Qual será o nome do suplemento? MyExcelSsoAddin
- Você gostaria de proporcionar suporte para qual aplicativo cliente do Office? Excel
Depois que você concluir o prompt, o gerador criará o projeto e instalará os componentes Node de suporte.
Registrar o aplicativo Microsoft Entra
Em seguida, registre o aplicativo Microsoft Entra e atualize o projeto para usar o aplicativo Microsoft Entra.
Dica
Para obter detalhes sobre como registrar o aplicativo Microsoft Entra manualmente, confira: Criar um suplemento do Office Node.js que usa logon único: registre o suplemento com Azure AD ponto de extremidade v2.0.
No prompt de comando, verifique se você está na pasta raiz do projeto. Em seguida, execute o seguinte comando:
npm run configure-sso
O comando iniciará um navegador e solicitará que você entre no Microsoft Entra ID. Verifique se você entra como um usuário que tem permissões para registrar um aplicativo Microsoft Entra, como um usuário atribuído à função de Administrador Global.
Após a autenticação, o script executará as seguintes tarefas:
- Registrar o aplicativo Microsoft Entra
- Definir as configurações de audiência e permissões do aplicativo
- Criar um novo segredo do cliente e salvá-lo no repositório secreto de estações de trabalho do desenvolvedor
- Atualizar o projeto com a ID do cliente do aplicativo Microsoft Entra
Aviso
O comando configure-sso falhará se o locatário Microsoft Entra estiver configurado para autenticação multifator (MFA)/autenticação de dois fatores. Nesse caso, você precisará criar manualmente o registro do aplicativo Microsoft Entra conforme descrito no artigo Criar um suplemento do Office Node.js que usa logon único: registre o suplemento com Azure AD artigo do ponto de extremidade v2.0.
Criar e testar o aplicativo
Execute o seguinte comando em um prompt de comando para transcompilar e iniciar o processo de depuração:
npm start
Teste o suplemento no cliente da área de trabalho do Word
Após alguns instantes, o Word será carregado com o botão do suplemento na faixa de opções e carregado no painel de tarefas.
Para testar o suplemento, selecione o botão Obter informações de perfil do usuário.
Se você ainda não tiver entrado com seu cliente do Office, será solicitado a fazê-lo.
Depois de entrar, o suplemento recuperará suas informações básicas de perfil do Microsoft Graph e as adicionará ao documento.
Atualizar o aplicativo para mostrar emails recentes
Agora, vamos atualizar o aplicativo do painel de tarefas para adicionar uma lista dos emails recentes recebidos pelo usuário conectado no momento com Microsoft Graph.
Atualizar as permissões do aplicativo Microsoft Entra
O aplicativo Microsoft Entra registrado deve primeiro receber permissões para o aplicativo.
Abra um navegador e navegue até o centro de administração Microsoft Entra (https://aad.portal.azure.com). Entre usando uma Conta Corporativa ou de Estudante que tenha direitos de administrador global para os locatários.
Na navegação mais à esquerda, selecione Gerenciar>permissões da API.
Adicione uma nova permissão selecionando Adicionar permissão.
Na tela Selecionar uma API, selecione Microsoft Graphe, em seguida, selecione Permissões delegadas. Pesquise e selecione a permissão Mail.Read e selecione Adicionar permissões.
Em seguida, selecione Conceder consentimento do administrador para a Contoso seguido de aceitar o prompt de confirmação selecionando Sim.
Atualizar o suplemento do painel de tarefas do Excel
A próxima etapa é atualizar o código no suplemento.
Atualizar o painel de tarefas
Localize e abra ./src/taskpane/taskpane.html.
Localize o seguinte elemento HTML no painel de tarefas:
<div class="ms-firstrun-instructionstep__welcome-body">
Localize o primeiro marcador no HTML e altere span conteúdo do elemento para:
<span class="ms-ListItem-primaryText">Click the <b>Get my last 10 emails</b> button.</span>
Localize o último marcador no HTML e altere span conteúdo do elemento para:
<span class="ms-ListItem-primaryText">Your last 10 emails will be displayed in the document.</span>
Localize o botão e altere o texto para: Get last 10 emails.
Atualizar o código do painel de tarefas
Agora, atualize o código que receberá os últimos 10 emails do usuário.
Localize e abra o arquivo ./src/helpers/ssoauthhelper.js.
Encontre a seguinte linha no método getGraphData():
const response = await sso.makeGraphApiCall(exchangeResponse.access_token);
Exclua essa linha e a substitua pelo código a seguir. Esse código usa um método diferente no auxiliar de logon único para enviar uma solicitação específica para o Microsoft Graph:
const endpoint = "/me/messages";
const urlParams = "?$select=receivedDateTime,subject,isRead&$orderby=receivedDateTime&$top=10";
const response = await sso.getGraphData(exchangeResponse.access_token, endpoint, urlParams);
Em seguida, localize e abra o arquivo ./src/helpers/documentHelper.js.
Localize o método writeDataToExcel(). Você substituirá a maior parte do código nesse método, mas deseja manter a estrutura básica. Exclua o conteúdo do método e substitua-o pelo seguinte código:
return Excel.run(function(context) {
const sheet = context.workbook.worksheets.getActiveWorksheet();
// TODO
return context.sync();
});
Primeiro, substitua o // TODO pelo seguinte código para criar alguns títulos de coluna na planilha:
const rangeHeading = sheet.getRange("A1:D1");
rangeHeading.values = [["Received Date/Time", "Subject", "Read?", "ID"]];
Em seguida, adicione o código a seguir após o código anterior que você acabou de adicionar. Isso obterá os resultados da solicitação Microsoft Graph e os converterá em uma matriz multidimensional para gravá-lo na planilha.
Em seguida, ele grava os resultados na planilha e formatada as colunas para que todos os dados sejam visíveis:
// convert data to a list
const mailResults = result.value;
for (let i = 0; i < mailResults.length; i++) {
if (mailResults[i] !== null) {
let innerArray = [];
innerArray.push(mailResults[i].receivedDateTime);
innerArray.push(mailResults[i].subject);
innerArray.push(mailResults[i].isRead);
innerArray.push(mailResults[i].id);
let data = [];
data.push(innerArray);
let rangeData = sheet.getRange(`A${i+2}:D${i+2}`);
rangeData.values = data;
}
}
rangeHeading.format.autofitColumns();
Criar e testar o aplicativo
Execute o seguinte comando em um prompt de comando para transcompilar e iniciar o processo de depuração:
npm start
Testar o suplemento no Excel
Após alguns instantes, o Word será carregado com o botão do suplemento na faixa de opções e carregado no painel de tarefas. Vamos testar isso no cliente Web do Excel.
Abra um navegador e navegue até o OneDrive (https://onedrive.com). Entre usando uma Conta Corporativa ou de Estudante.
Adicione uma nova pasta de trabalho do Excel selecionando o botão Novo e, em seguida, selecione Pasta de trabalho do Excel.
Instale o suplemento do Word ao fazer o sideload dele. Na faixa de opções, selecione Inserir>Suplementos.
Na caixa de Suplementos do Office, selecione Carregar Meu Suplemento.
Selecione o arquivo manifest.xml na raiz do projeto e selecione Carregar.
O Microsoft Word realizará o sideload do suplemento e exibirá o botão Mostrar Painel de Tarefas na faixa de opções, assim como o cliente da área de trabalho.
Selecione o botãoMostrar painel de tarefas e, em seguida, selecione o botãoObter os últimos 10 emails.
Como você já está conectado, após alguns instantes, você verá os emails recentes aparecerem na planilha sem precisar entrar.
