Criar uma folha de cálculo do Excel a partir da sua página Web, preenchê-la com dados e incorporar o seu Suplemento do Office

Os parceiros da Microsoft com aplicações Web SaaS sabem que, muitas vezes, os clientes querem abrir os seus dados a partir de uma página Web numa folha de cálculo do Excel. Utilizam o Excel para fazer análises sobre os dados ou outros tipos de processamento de números. Em seguida, carregam os dados de volta para o site.

Em vez de vários passos para exportar os dados do site para um ficheiro de .csv, importe o ficheiro de .csv para o Excel, trabalhe com os dados e, em seguida, exporte-os do Excel e carregue-os novamente para o site, podemos simplificar este processo para um clique com um botão.

Este artigo mostra como adicionar um botão do Excel ao seu site. Quando um cliente escolhe o botão, cria automaticamente uma nova folha de cálculo com os dados pedidos, carrega-a para o OneDrive do cliente e abre-a no Excel num novo separador do browser. Com um clique, os dados pedidos são abertos no Excel e formatados corretamente. Além disso, o padrão incorpora o seu próprio Suplemento do Office dentro da folha de cálculo para que os clientes possam continuar a aceder aos seus serviços a partir do contexto do Excel.

Os parceiros da Microsoft que implementaram este padrão viram aumentar a satisfação dos clientes. Também viram um aumento significativo no envolvimento com os respetivos suplementos ao incorporá-los na folha de cálculo do Excel. Recomendamos que, se tiver um site para os clientes trabalharem com dados, considere implementar este padrão na sua própria solução.

Pré-requisitos

• Visual Studio 2022 ou posterior. Adicione a carga de trabalho de desenvolvimento do Office/SharePoint ao configurar o Visual Studio.
• Visual Studio Code.
• Microsoft 365. Pode obter um sandbox gratuito para programadores que fornece uma subscrição de programador Microsoft 365 E5 renovável de 90 dias. O sandbox do programador inclui uma subscrição do Microsoft Azure que pode utilizar para registos de aplicações em passos posteriores neste artigo. Se preferir, pode utilizar uma subscrição separada do Microsoft Azure para registos de aplicações. Obtenha uma subscrição de avaliação no Microsoft Azure.
• Um ou mais ficheiros e pastas no OneDrive na conta do Microsoft 365.

Executar o código de exemplo

O código de exemplo para este artigo chama-se Criar uma folha de cálculo a partir do seu site, povoá-la com dados e incorporar o seu suplemento do Excel Para executar o exemplo, siga as instruções no leia-me.

Arquitetura da solução

A solução descrita neste artigo adiciona um botão Abrir no Microsoft Excel ao site e interage com Azure Functions e o Microsoft API do Graph. A seguinte sequência de eventos ocorre quando o utilizador quer abrir os dados numa nova folha de cálculo do Excel.

1. O utilizador seleciona o botão Abrir no Microsoft Excel . A página Web transmite os dados para uma função numa aplicação Azure Functions.
2. A função utiliza o SDK Open XML para criar uma nova folha de cálculo do Excel na memória. Preenche a folha de cálculo com os dados e incorpora o seu Suplemento do Office.
3. A função devolve a folha de cálculo como uma cadeia codificada base64 para a página Web.
4. A página Web chama o Microsoft API do Graph para carregar a folha de cálculo para o OneDrive do utilizador.
5. O Microsoft Graph devolve a localização do URL da Web do novo ficheiro de folha de cálculo.
6. A página Web abre um novo separador do browser para abrir a folha de cálculo no URL da Web. A folha de cálculo contém os dados e o suplemento.

Principais partes da solução

A solução tem dois projetos que cria:

• Uma aplicação Azure Functions que contém uma FunctionCreateSpreadsheet função.
• Um Node.js projeto de aplicação Web.

As secções seguintes descrevem conceitos importantes e detalhes de implementação para construir a solução. Pode encontrar uma implementação de referência completa no código de exemplo para obter detalhes de implementação adicionais.

Botão excel e IU Fluent

Precisa de um botão no site que cria a folha de cálculo do Excel. Uma melhor prática é utilizar a IU Fluente para ajudar os seus utilizadores a transitar entre produtos Microsoft. Deve sempre utilizar um ícone do Office para indicar que aplicação do Office será iniciada a partir da sua página Web. Para obter mais informações, consulte Ícones de Marca do Office no portal fluente do programador da IU.

Iniciar sessão do utilizador

O código de exemplo é criado a partir do exemplo de identidade da Microsoft denominado aplicação de página única Vanilla JavaScript com MSAL.js para autenticar os utilizadores para chamar o Microsoft Graph. Todo o código de autenticação e IU são provenientes deste exemplo. Veja este exemplo para obter mais informações sobre como escrever código para autenticação e autorização. Para obter uma lista completa dos exemplos de identidade de uma vasta gama de plataformas, veja plataforma de identidade da Microsoft exemplos de código.

Criar a folha de cálculo com o SDK Open XML

O código de exemplo utiliza o SDK Open XML para criar a folha de cálculo. Uma vez que o SDK Open XML utiliza .NET, está encapsulado numa aplicação Azure Functions com o nome FunctionCreateSpreadsheet. Pode chamar esta função a partir da sua aplicação Web Node.js. FunctionCreateSpreadsheet utiliza a SpreadsheetBuilder classe auxiliar para criar uma nova folha de cálculo na memória. O código baseia-se em Criar um documento de folha de cálculo ao fornecer um nome de ficheiro (Open XML SDK).

Preencher a folha de cálculo com dados

A FunctionCreateSpreadsheet função aceita um corpo JSON que contém os dados de linha e coluna. Isto é transmitido ao SpreadsheetBuilder.InsertData método que itera todas as linhas e colunas e as adiciona à folha de cálculo.

Grande parte da SpreadsheetBuilder classe contém código gerado pelas Ferramentas de Produtividade do SDK Open XML 2.5. Estes estão disponíveis na ligação para o SDK Open XML 2.5.

Incorporar o suplemento do Office na folha de cálculo

A SpreadsheetBuilder classe também incorpora o suplemento Script Lab dentro da folha de cálculo e configura para ser apresentado quando o documento é aberto.

O método SpreadsheetBuilder.GenerateWebExtensionPart1Content no ficheiro SpreadsheetBuilder.cs define a referência ao ID de Script Lab no Microsoft Marketplace:

We.WebExtensionStoreReference webExtensionStoreReference1 = new We.WebExtensionStoreReference() { Id = "wa104380862", Version = "1.1.0.0", Store = "en-US", StoreType = "OMEX" };

• O valor StoreType é "OMEX", um alias para o Microsoft Marketplace.
• O valor store é "en-US" encontrado na secção cultura do Microsoft Marketplace para Script Lab.
• O valor do ID é o ID do recurso do Microsoft Marketplace para Script Lab.

Pode alterar estes valores para incorporar o seu próprio Suplemento do Office. Isto torna-o detetável para o utilizador e aumenta a interação com o seu suplemento e serviços Web. Se o suplemento for implementado através da implementação central, utilize antes os seguintes valores.

We.WebExtensionStoreReference webExtensionStoreReference1 = new We.WebExtensionStoreReference() { Id = "<Your add-in GUID>", Version = "<Your version>", Store = "excatalog", StoreType = "excatalog" };
We.WebExtensionStoreReference webExtensionStoreReference2 = new We.WebExtensionStoreReference() { Id = "<Your add-in GUID>", Version = "<Your version>", Store = "omex", StoreType = "omex" };            
webExtensionReferenceList1.Append(webExtensionStoreReference2);

Para obter mais informações sobre valores alternativos para estes atributos, consulte Abrir automaticamente um painel de tarefas com um documento e [MS-OWEXML]: CT_OsfWebExtensionReference

Carregar a folha de cálculo para o OneDrive

Quando a folha de cálculo é totalmente construída, a FunctionCreateSpreadsheet função devolve uma versão de cadeia codificada Base64 da folha de cálculo para a aplicação Web. Em seguida, a aplicação Web utiliza o Microsoft API do Graph para carregar a folha de cálculo para o OneDrive do utilizador. A aplicação Web cria o ficheiro em \openinexcel\spreadsheet.xlsx, mas pode modificar o código para utilizar qualquer pasta e nome de ficheiro que preferir.

Considerações adicionais para a sua solução

A solução de todos é diferente em termos de tecnologias e abordagens. As seguintes considerações irão ajudá-lo a planear como modificar a sua solução para abrir documentos e incorporar o seu Suplemento do Office.

Ler propriedades personalizadas quando o suplemento é iniciado

Quando incorporar o suplemento na folha de cálculo, pode incluir propriedades personalizadas. O SpreadsheetBuilder.cs ficheiro inclui código comentado que mostra como inserir um nome de utilizador se tiver uma userName variável.

    // CUSTOM MODIFICATION BEGIN
    // Uncomment the following code to add your own custom name/value pair properties for the add-in.
    // We.WebExtensionProperty webExtensionProperty2 = new We.WebExtensionProperty() { Name = "userName", Value = userName };
    // webExtensionPropertyBag1.Append(webExtensionProperty2);
    // CUSTOM MODIFICATION END

Anule o comentário do código e altere-o para adicionar as propriedades do cliente necessárias. No seu suplemento, utilize o método obter definições do Office para obter uma propriedade personalizada. O exemplo seguinte mostra como obter a propriedade do nome de utilizador a partir da folha de cálculo.

let userName = Office.context.document.settings.get('userName'));

Veja Manter o estado e as definições do suplemento para obter detalhes completos sobre como ler propriedades personalizadas quando o suplemento é iniciado.

Utilizar o início de sessão único

Para simplificar a autenticação, recomendamos que o suplemento implemente o início de sessão único. Isto garante que o utilizador não precisa de iniciar sessão uma segunda vez para aceder ao seu suplemento. Para obter mais informações, consulte Ativar o início de sessão único para Suplementos do Office

Confira também

• Bem-vindo ao SDK Open XML 2.5 para Office
• Abrir automaticamente um painel de tarefas com um documento
• Persistir o estado e as configurações do suplemento
• Criar um documento de planilha fornecendo um nome de arquivo