Como conectar um plugin ao Google Planilhas no FastReport .NET

O Google Planilhas é um aplicativo em nuvem para trabalhar com planilhas eletrônicas. Assim como o Microsoft Excel, o serviço Google Planilhas pode ser usado como fonte de dados para relatórios. No entanto, em contraste com as soluções para desktop, este é um aplicativo web; portanto, a conexão tem características distintas. 

Neste artigo, vamos analisar como começar o trabalho com o Google Planilhas no FastReport .NET. Você aprenderá como configurar o acesso à API por meio do Google Cloud Console, obter as credenciais necessárias e compilar e conectar o plugin. Também mostraremos como configurar a conexão no Designer de relatórios e por meio de código.

Para começar a usar o Google Planilhas, você precisa preparar suas credenciais de login. Três tipos de credenciais são aceitos:

1. ClientID e ClientSecret – um par de chaves para identificar o aplicativo usando o protocolo OAuth2.0;
2. Chave da API (API Key) – um token exclusivo para acesso direto à API do Google;
3. O arquivo .json de dados do cliente – um arquivo de configuração contendo Client ID e Secret.

Você pode obter esses dados por meio do Google Cloud Console. Após fazer login, crie um novo projeto no console: no painel superior, clique na lista suspensa de projetos (“Select a project”), selecione ‘Newproject’ na janela que se abre, dê um nome ao projeto (por exemplo, “FastReport”) e clique em “Create”. Assim que criado, o projeto será ativado automaticamente. Caso contrário, selecione-o manualmente na lista de projetos. 

Em seguida, abra o menu lateral e vá até a seção “APIs & Services”, subseção “Library”. Aqui, é necessário ativar o acesso à API do Google Planilhas – essa permissão permitirá que seu aplicativo interaja programaticamente com as Google Planilhas. 

No campo de busca, digite “Google Planilhas API”, selecione este serviço e clique em “Enable”. Após a ativação da API, o aplicativo terá a capacidade de ler e escrever dados no Google Planilhas, o que é um requisito obrigatório para o funcionamento do plugin. 

Em seguida, passamos para a subseção “OAuthconsentscreen”.

Nesta etapa, configuraremos o OAuth para o nosso aplicativo. Depois de clicar em “Get started”, o assistente de configuração da Plataforma do Google Auth será aberto.

Na primeira etapa, preencha as informações do aplicativo: insira um nome (por exemplo, “FastReportNET”) e um endereço de e-mail de suporte ao usuário e clique em “Next”.

Em seguida, é necessário escolher o tipo de usuários. Como estamos criando um aplicativo para testes, selecione “External” e avance para a próxima etapa clicando em “Next”.

Na próxima etapa, configuramos os e-mails de contato para notificações sobre alterações no projeto. 

Na etapa final, confirme sua concordância com a Google API Services User Data Policy (a Política de Dados do Usuário dos Serviços de API do Google), marcando a caixa apropriada, e conclua a configuração clicando em “Create”.

Após criar a configuração do OAuth, acesse a subseção “Audience”. Neste ponto, você precisa adicionar sua conta do Google à lista de usuários de teste. Clique em “Addusers”, insira seu endereço de e-mail (Gmail) e salve as alterações.

Este é um requisito de segurança do Google: enquanto o aplicativo estiver em status “Testing” e não tiver sido oficialmente verificado, somente usuários explicitamente designados terão acesso a ele. Sem adicionar sua conta a esta lista, a autorização falhará. 

É importante observar que, antes da verificação, um aplicativo pode ter no máximo 100 usuários de teste durante toda a sua existência.

Em seguida, acesse a subseção “DataAccess”. Nesta etapa, definiremos os direitos de acesso que nosso aplicativo solicitará ao usuário ao se conectar.

Clique no botão “Add or remove scopes” para abrir a lista de permissões disponíveis. No campo de filtro, digite “API:GoogleSheetsAPI” e selecione a opção com a descrição "SeeallyourGoogleSheetsspreadSheets" (acesso somente leitura). Essa opção é suficiente para gerar relatórios e é mais segura: o aplicativo não poderá modificar ou excluir dados das planilhas. Marque a caixa da permissão selecionada, clique em “Update” e, em seguida, em “Save”. 

Após concluir a configuração da “OAuthconsentscreen” e adicionar usuários de teste, passamos para a criação de credenciais. Nesta etapa, obteremos as chaves de acesso necessárias para conectar ao Google Planilhas a partir do FastReport .NET.

Retorne à seção “APIs & Services” e navegue até a subseção “Credentials”. Aqui, clique no botão “Createcredentials” na parte superior da página.

O sistema oferecerá três opções para criar credenciais, mas duas são as mais adequadas para nossos propósitos: API Key e OAuth Client ID. Discutiremos cada opção com mais detalhes abaixo. A terceira opção disponível, Service Account, não será abordada, pois destina-se a aplicativos de servidor e processos automatizados sem intervenção do usuário.

Ambas as opções têm suas vantagens: a Chave de API é mais fácil de usar, mas o OAuth 2.0 oferece um nível de segurança mais alto, pois não armazena chaves em texto simples, mas usa um mecanismo de token de acesso.

Criando credenciais por meio de API Key

Vamos começar com a API Key — é o método de autenticação mais simples, adequado para acesso básico à API. Importante: a API Key só é adequada para planilhas públicas do Google Planilhas. Para acessar planilhas privadas, use o OAuth 2.0.

Selecione a opção “APIkey” na lista suspensa.

Uma janela da criação de chave será aberta. No campo “Name”, insira um nome para a chave. Deixe a opção “AuthenticateAPIcallsthroughaserviceaccount” desmarcada – ela não é necessária para os nossos propósitos.

Na seção “Applicationrestrictions”, selecione “None” (sem restrições), pois o FastReport .NET funciona como um aplicativo de desktop local.

Na seção “APIrestrictions”, selecione “Restrictkey” (restringir chave) – esta é uma configuração de segurança importante. Após selecioná-la, uma lista de APIs disponíveis será exibida. Encontre e selecione “GoogleSheetsAPI”. Isso impedirá o uso não autorizado da chave para acessar outros serviços do Google.

Após a configuração, clique no botão “Create”. 

Criando credenciais por meio de OAuth Client ID

O segundo tipo de credencial é OAuth Client ID. Este é um método mais seguro que utiliza o protocolo OAuth 2.0 para autorização.

Na lista suspensa “Createcredentials” selecione “OAuthclientID”, selecione o tipo de aplicativo “Desktop app” (já que o FastReport .NET é executado como um aplicativo local) e insira um nome de cliente. Após a criação, o sistema exibirá o Client ID e o Client Secret e solicitará que você baixe um arquivo .json contendo esses dados. Essas credenciais serão necessárias para conectar-se ao Google Planilhas no designer do FastReport.

A conexão com o Google Planilhas é implementada por meio de um plugin, portanto, ele deve ser compilado antes da configuração. O projeto está localizado na pasta  "Extras\Core\FastReport.Data\FastReport.Data.GoogleSheets."

Após compilar o projeto, conecte o plugin ao FastReport. Para utilizá-lo no designer de relatórios, adicionamos o arquivo DLL compilado por meio do menu de configurações:

Para integração programática, adicione o assembly às dependências do projeto e registre a conexão usando o seguinte código durante a inicialização do aplicativo:

FastReport.Utils.RegisteredObjects.AddConnection(typeof(GoogleSheetsDataConnection));

Uma descrição detalhada de como criar a conexão via código está no arquivo readme.txt, que é fornecido junto com o projeto do plugin.

Para criar a conexão, vá até a aba “Dados” e selecione “Nova fonte de dados”. Na janela do assistente, clique em “Nova conexão” e escolha ‘Conexão com o Google Planilhas”.

No campo "ID ou URL da planilha", insira o ID ou a URL da planilha. Por exemplo, para a URL  https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms o ID da planilha seria "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms".

• A opção “Cabeçalhos de coluna da primeira linha” utiliza a primeira linha da planilha do Google Planilhas como nomes de coluna.
• A opção “Adicionar planilhas ocultas” inclui planilhas ocultas na interface do Google Planilhas na lista de planilhas.

Para fazer login, basta clicar em “OK” – se você não tiver nenhuma credencial salva, o formulário de login será aberto automaticamente. Como alternativa, você pode abrir o formulário de login manualmente clicando em “Login” e inserindo suas credenciais. Observe que os dados inseridos só serão validados depois que você clicar em “OK” no formulário principal.

A escolha do método de autorização afeta o processo subsequente:

• Ao conectar-se por meio de API Key, a autorização no navegador não é necessária; portanto, a chave é passada diretamente na solicitação, mas este método funciona apenas com planilhas públicas.
• Ao conectar-se por meio de OAuth 2.0 a autorização será necessária no navegador – este método é adequado tanto para planilhas públicas quanto privadas.

Se o OAuth 2.0 for selecionado, um formulário de espaço reservado será exibido no Designer durante o processo de autorização, permitindo que você cancele o processo:

A autorização do navegador funciona da seguinte forma: na janela do navegador que se abre, faça login na conta do Google cujo endereço de e-mail foi adicionado à lista de usuários de teste durante a etapa de configuração do OAuth. Se você tentar fazer login com uma conta diferente que não esteja incluída na lista de usuários de teste, verá uma mensagem de erro de acesso informando que o aplicativo está disponível apenas para usuários de teste.

A próxima etapa exibirá um aviso de que o aplicativo não passou na análise do Google. Esta é a mensagem padrão para aplicativos em modo de teste. Clique em “Continuar” para conceder acesso.

Uma tela de solicitação de permissões será exibida, indicando que o aplicativo de nome  “FastReportNET” precisa de permissão para visualizar todas as planilhas do Google Planilhas. Revise as permissões solicitadas e clique em “Continuar” para confirmar.

Após a autorização bem-sucedida, uma aba será aberta com o texto “Closethewindow”. Isso significa que suas credenciais foram salvas e você pode fechar o navegador.

Retorne ao Designer do FastReport .NET. Se a conexão for bem-sucedida, a próxima janela exibirá uma lista de tabelas do Google Planilhas disponíveis para seleção. As capturas de tela abaixo mostram como a lista de campos muda dependendo da opção “Cabeçalhos de coluna da primeira linha”:

• Se esta opção estiver habilitada, a primeira linha da tabela será usada como nomes de coluna (Nome do Aluno, Sexo, etc.).
• Se esta opção estiver desabilitada, as colunas receberão nomes padrão (Coluna1, Coluna2, etc.).

Os dados do Google Planilhas são importados no mesmo formato em que aparecem na planilha — como texto e números. Objetos visuais são completamente ignorados: imagens, gráficos, tabelas e desenhos (formas, linhas, botões). Objetos interativos são convertidos em texto: caixas de seleção são exibidas como texto (verdadeiro/falso) e listas suspensas são substituídas pelo valor exibido no Google Planilhas.

Um exemplo do resultado final do trabalho com o Google Planilhas no FastReport.NET — os dados recuperados com sucesso de uma planilha na nuvem são exibidos no relatório.

Este artigo detalhou o processo de conexão do plugin ao Google Planilhas no FastReport .NET — desde a configuração do acesso à API por meio do Google Cloud Console até a autorização final e a importação de dados. Após a autorização bem-sucedida, os dados do Google Planilhas são importados corretamente para o designer de relatórios — com exceção dos objetos visuais e interativos, que são ignorados ou convertidos em texto.