Как подключить плагин к Google Sheets в FastReport .NET

Google Sheets – это облачное приложение для работы с электронными таблицами. Как и Microsoft Excel, сервис Google Sheets можно использовать в качестве источника данных для отчётов. Однако, в отличие от десктопных решений, это веб-приложение, поэтому подключение имеет свои особенности. 

В этой статье рассмотрим, как начать работу с Google Sheets в FastReport .NET. Вы узнаете, как настроить доступ к API через Google Cloud Console, получить необходимые учётные данные, собрать и подключить плагин. Также покажем, как настроить подключение в дизайнере отчётов и из кода.

Для начала работы с Google Sheets необходимо подготовить учётные данные для авторизации. Поддерживаются три типа учетных данных: 

1. Client ID и Client Secret – пара ключей для идентификации приложения по протоколу OAuth 2.0;
2. API ключ – уникальный токен для прямого доступа к Google API;
3. .json-файл с данными клиента – файл конфигурации, содержащий Client ID и Secret.

Получить эти данные можно через Google Cloud Console. После авторизации в консоли создаем новый проект: в верхней панели нажмите на выпадающий список проектов («Select a project»), в открывшемся окне выберите «New project», задайте проекту имя (например, FastReport) и нажмите «Create». После создания проект автоматически станет активным – если этого не произошло, выберите его вручную из списка проектов.

Далее открываем боковое меню и переходим в раздел «APIs & Services», подраздел «Library». Здесь необходимо включить доступ к Google Sheets API – это разрешение позволит Вашему приложению программно взаимодействовать с таблицами Google.

В поиске вводим «Google Sheets API», выбираем этот сервис и нажимаем «Enable». После активации API приложение получит возможность читать и записывать данные в Google Sheets, что является обязательным условием для работы плагина.

Затем переходим в подраздел «OAuth consent screen». 

На этом этапе будет происходить настройка OAuth для нашего приложения. После нажатия кнопки «Get started» откроется мастер настройки Google Auth Platform.

На первом шаге заполняем информацию о приложении: указываем название (например, FastReportNET) и Email для поддержки пользователей, после чего нажимаем кнопку «Next».

Далее следует выбор типа пользователей. Поскольку сейчас мы создаём приложение для тестирования, выбираем «External» и переходим к следующему шагу, нажав «Next».

На следующем шаге задаем контактные Email, предназначенные для уведомлений об изменениях в проекте.

На заключительном шаге подтверждаем согласие с Google API Services User Data Policy (Политика использования пользовательских данных сервисов Google API), установив соответствующую галочку, и завершаем настройку, нажав кнопку «Create».

После создания OAuth конфигурации переходим в подраздел «Audience». На этом этапе необходимо добавить свой Google-аккаунт в список тестовых пользователей. Нажимаем кнопку «Add users», вводим свой email (Gmail) и сохраняем изменения.

Это требование безопасности Google: пока приложение находится в статусе «Testing» и не прошло официальную верификацию, доступ к нему имеют только явно указанные пользователи. Без добавления Вашего аккаунта в этот список авторизация завершится ошибкой доступа.

Важно учитывать, что до прохождения верификации приложение может иметь не более 100 тестовых пользователей за весь период существования. 

Далее переходим в подраздел «Data Access». На этом этапе определим права доступа, которые наше приложение запросит у пользователя при подключении. 

Нажимаем кнопку «Add or remove scopes», чтобы открыть список доступных разрешений. В поле фильтра вводим «API: Google sheets API», и выбираем вариант с описанием «See all your Google Sheets spreadsheets» (доступ только для чтения). Такой вариант достаточен для формирования отчётов и безопаснее: приложение не сможет изменить или удалить данные из таблиц. Отмечаем выбранное разрешение галочкой, нажимаем «Update», а затем «Save».

После завершения настройки «OAuth consent screen» и добавления тестовых пользователей переходим к созданию учётных данных (Credentials). На этом этапе получим ключи доступа, которые потребуются для подключения к Google Sheets из FastReport .NET.

Возвращаемся назад, в раздел «APIs & Services» и переходим в подраздел «Credentials». Здесь нажимаем кнопку «Create credentials» в верхней части страницы. 

Система предложит три варианта создания учётных данных, но для нашей задачи подходят два основных: API Key и OAuth Client ID. Подробнее каждый вариант рассмотрим ниже. Третий доступный вариант – Service Account – не будет рассмотрен, так как он предназначен для серверных приложений и автоматизированных процессов без участия пользователя.

Оба варианта имеют свои преимущества: API Key проще в использовании, но OAuth 2.0 обеспечивает более высокий уровень безопасности, так как не хранит ключи в открытом виде, а использует механизм токенов доступа.

Создание учетных данных через API Key

Начнем с API Key – это простейший способ аутентификации, который подходит для базового доступа к API. Важно: API Key подходит только для публичных таблиц Google Sheets. Для доступа к приватным таблицам используйте OAuth 2.0.

В выпадающем списке выбираем вариант API key.

Откроется окно создания ключа, в поле Name задаём имя ключа. Опцию «Authenticate API calls through a service account» оставляем неотмеченной – для наших задач она не требуется.

В разделе «Application restrictions» выбираем None (без ограничений), так как FastReport .NET работает как локальное десктопное приложение.

В разделе «API restrictions» выбираем Restrict key (ограничить ключ) – это важная настройка безопасности. После выбора появится список доступных API, где нужно найти и отметить Google Sheets API. Это предотвратит несанкционированное использование ключа для доступа к другим сервисам Google.

После настройки нажимаем кнопку «Create». 

Создание учетных данных через OAuth Client ID

Второй тип учетных данных – OAuth Client ID. Это более безопасный метод, использующий протокол OAuth 2.0 для авторизации. 

В выпадающем списке «Create credentials» выбираем вариант «OAuth client ID», указываем тип приложения «Desktop app» (так как FastReport .NET работает как локальное приложение) и задаём имя клиента. После создания система отобразит Client ID и Client Secret, а также предложит скачать .json-файл с этими данными. Именно эти учётные данные потребуются при подключении к Google Sheets в дизайнере FastReport.

Подключение к Google Sheets реализовано через плагин, поэтому перед настройкой его необходимо собрать. Проект находится в папке по пути «Extras\Core\FastReport.Data\FastReport.Data.GoogleSheets».

После сборки проекта подключаем плагин к FastReport. Для работы в дизайнере отчётов добавляем собранный DLL-файл с помощью меню настроек:

Для программной интеграции добавляем сборку в зависимости проекта и регистрируем подключение с помощью следующего кода при инициализации приложения: 

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

Подробное описание создания подключения из кода находится в файле readme.txt, который поставляется вместе с проектом плагина.

Для создания подключения переходим на вкладку «Данные» и выбираем «Новый источник данных». В окне мастера нажимаем «Новое подключение» и выбираем «Подключение к Google Sheets». 

В поле «Идентификатор таблицы или URL адрес» указываем идентификатор таблицы или URL адрес. Например, при URL адресе  https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms идентификатором таблицы будет значение «1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms».

• Опция «Заголовки столбцов из первой строки» использует первую строку таблицы Google Sheets в качестве имён колонок.
• Опция «Добавлять скрытые листы» включает в список таблиц листы, скрытые в интерфейсе Google Sheets.

Для авторизации можно просто нажать «OK» – если сохраненные учетные данные отсутствуют, автоматически откроется форма авторизации. Либо открываем форму авторизации самостоятельно, нажав кнопку «Вход», и вручную вводим учётные данные. Стоит учесть, что проверка введённых данных происходит только после нажатия «OK» на основной форме.

Выбор метода авторизации влияет на дальнейший процесс:

• При подключении через API Key авторизация в браузере не требуется – ключ передаётся напрямую в запросе, но метод работает только с публичными таблицами.
• При подключении через OAuth 2.0 потребуется авторизация в браузере – этот метод подходит для публичных и приватных таблиц.

Если выбран метод OAuth 2.0, то в процессе авторизации в дизайнере отображается форма-заглушка, по которой можно отменить процесс:

Авторизация в браузере происходит следующим образом: в открывшемся окне браузера нужно войти в аккаунт Google, Email которого был добавлен в список тестовых пользователей на этапе настройки OAuth. Если попытаться войти под другим аккаунтом, который не указан в списке тестовых пользователей, то появится ошибка доступа с сообщением, что приложение доступно только для тестовых пользователей.

На следующем шаге появится предупреждение о том, что приложение не прошло проверку Google. Это стандартное сообщение для приложений в режиме тестирования. Нажимаем «Продолжить», чтобы предоставить доступ.

Отобразится экран запроса прав доступа, где указано, что приложению «FastReportNET» требуется разрешение на просмотр всех таблиц Google Sheets. Проверяем запрошенные права и нажимаем «Продолжить» для подтверждения.

После успешной авторизации откроется вкладка с текстом «Close the window» – это означает, что учётные данные успешно сохранены, и браузер можно закрыть.

Возвращаемся в дизайнер FastReport .NET. Если подключение прошло успешно, в следующем окне отобразится список таблиц из Google Sheets, доступных для выбора. На скриншотах ниже показано, как меняется список полей в зависимости от использования опции «Заголовки столбцов из первой строки»:

• Если опция включена, первая строка таблицы используется как имена колонок (Student Name, Gender и т.д.).
• Если опция выключена, колонки получают стандартные имена (Column1, Column2 и т.д.).

Данные из Google Sheets импортируются в том же виде, в каком они представлены в таблице – в виде текста и чисел. Визуальные объекты полностью игнорируются: изображения, диаграммы, графики, рисунки (фигуры, линии, кнопки). Интерактивные объекты преобразуются в текст: флажки (чекбоксы) отображаются как текст (true/false), а вместо выпадающего списка будет отображаемое в Google Sheets значение.

Пример итогового результата работы с Google Sheets в FastReport .NET – данные, которые были успешно получены из облачной таблицы, отображены в отчёте.

В статье был подробно рассмотрен процесс подключения плагина к Google Sheets в FastReport .NET — от настройки доступа к API через Google Cloud Console до финальной авторизации и импорта данных. После успешной авторизации данные из Google Sheets корректно импортируются в дизайнер отчётов — за исключением визуальных и интерактивных объектов, которые либо игнорируются, либо преобразуются в текстовое представление.