Google Sheets-Plugin in FastReport .NET einbinden

Google Sheets ist eine Cloud-Anwendung für die Arbeit mit Tabellenkalkulationen. Wie Microsoft Excel kann Google Sheets als Datenquelle für Berichte verwendet werden. Im Gegensatz zu Desktop-Lösungen handelt es sich jedoch um eine Webanwendung, daher hat die Anbindung ihre eigenen Besonderheiten.

In diesem Artikel betrachten wir, wie Sie mit Google Sheets in FastReport .NET arbeiten können. Sie erfahren, wie Sie den Zugriff auf die API über die Google Cloud Console einrichten, die erforderlichen Zugangsdaten erhalten, das Plugin kompilieren und anbinden. Außerdem zeigen wir, wie Sie die Verbindung im Berichtsdesigner und über Code konfigurieren.

Für die Arbeit mit Google Sheets müssen zunächst Zugangsdaten für die Autorisierung vorbereitet werden. Drei Arten von Zugangsdaten werden unterstützt:

1. Client ID und Client Secret, ein Schlüsselpaar zur Identifikation der Anwendung über das OAuth 2.0-Protokoll.
2. API-Schlüssel, ein eindeutiger Token für den direkten Zugriff auf die Google API.
3. JSON-Datei mit Clientdaten, eine Konfigurationsdatei, die Client ID und Secret enthält.

Diese Daten können über die Google Cloud Console bezogen werden. Nach der Anmeldung in der Console erstellen Sie ein neues Projekt: Klicken Sie in der oberen Leiste auf das Dropdown-Menü der Projekte („Select a project“), wählen Sie im sich öffnenden Fenster „New project“, geben Sie dem Projekt einen Namen (z. B. FastReport) und klicken Sie auf „Create“. Nach der Erstellung wird das Projekt automatisch aktiv. Falls dies nicht der Fall sein sollte, wählen Sie es manuell aus der Projektliste aus.

Anschließend öffnen Sie das Seitenmenü und wechseln zum Bereich „APIs & Services“, Unterbereich „Library“. Hier müssen Sie den Zugriff auf die Google Sheets API aktivieren. Diese Berechtigung erlaubt es Ihrer Anwendung, programmatisch mit Google-Tabellen zu interagieren.

Geben Sie in die Suche „Google Sheets API“ ein, wählen Sie diesen Dienst aus und klicken Sie auf „Enable“. Nach der Aktivierung der API erhält die Anwendung die Möglichkeit, Daten in Google Sheets zu lesen und zu schreiben. Dies ist eine zwingende Voraussetzung für die Funktion des Plugins.

Anschließend wechseln Sie in den Unterbereich „OAuth consent screen“.

In diesem Schritt wird OAuth für die Anwendung konfiguriert. Nach dem Klicken auf die Schaltfläche «Get started» öffnet sich der Einrichtungsassistent der Google Auth Platform.

Im ersten Schritt füllen Sie die Informationen zur Anwendung aus: Geben Sie einen Namen (z. B. FastReportNET) und eine E-Mail für den Benutzersupport an und klicken Sie dann auf „Next“.

Als nächstes folgt die Auswahl des Benutzertyps. Bei der Erstellung einer Testanwendung wählen Sie „External“ und wechseln zum nächsten Schritt durch Klicken auf „Next“.

Im nächsten Schritt geben Sie Kontakt-E-Mails für Benachrichtigungen über Änderungen am Projekt ein.

Im letzten Schritt bestätigen Sie die Zustimmung zur Google API Services User Data Policy, indem Sie das entsprechende Kontrollkästchen aktivieren, und schließen die Einrichtung durch Klicken auf „Create“ ab.

Nach der Erstellung der OAuth-Konfiguration wechseln Sie in den Unterbereich „Audience“. In diesem Schritt müssen Sie Ihr Google-Konto zur Liste der Testbenutzer hinzufügen. Klicken Sie auf „Add users“, geben Sie Ihre E-Mail (Gmail) ein und speichern Sie die Änderungen.

Dies ist eine Sicherheitsanforderung von Google: Solange sich die Anwendung im Status „Testing“ befindet und nicht offiziell verifiziert wurde, haben nur explizit angegebene Benutzer Zugriff darauf. Ohne Hinzufügen Ihres Kontos zu dieser Liste schlägt die Autorisierung mit einer Zugriffsverweigerung fehl.

Es ist wichtig zu beachten, dass die Anwendung vor der Verifizierung nicht mehr als 100 Testbenutzer über die gesamte Lebensdauer haben darf.

Als nächstes wechseln Sie in den Unterbereich „Data Access“. In diesem Schritt legen Sie die Zugriffsrechte fest, die Ihre Anwendung beim Verbinden vom Benutzer anfordern wird.

Klicken Sie auf „Add or remove scopes“, um die Liste der verfügbaren Berechtigungen zu öffnen. Geben Sie im Filterfeld „API: Google Sheets API“ ein und wählen Sie die Variante mit der Beschreibung „See all your Google Sheets spreadsheets“ (schreibgeschützter Zugriff). Diese Variante ist für die Berichterstellung ausreichend und sicherer: Die Anwendung kann keine Daten in den Tabellen ändern oder löschen. Markieren Sie die ausgewählte Berechtigung mit einem Häkchen, klicken Sie auf „Update“ und dann auf „Save“.

Nach Abschluss der Konfiguration des „OAuth consent screen“ und dem Hinzufügen von Testbenutzern wechseln Sie zur Erstellung der Zugangsdaten (Credentials). In diesem Schritt erhalten Sie die Zugriffsschlüssel, die für die Verbindung zu Google Sheets aus FastReport .NET benötigt werden.

Kehren Sie zurück zum Bereich „APIs & Services“ und wechseln Sie in den Unterbereich „Credentials“. Klicken Sie hier auf die Schaltfläche „Create credentials“ oben auf der Seite.

Das System bietet drei Optionen zur Erstellung von Zugangsdaten an, aber für Ihre Aufgabe sind zwei Hauptoptionen geeignet: API Key und OAuth Client ID. Jede Option wird unten detaillierter betrachtet. Die dritte verfügbare Option (Service Account) wird nicht behandelt, da sie für Serveranwendungen und automatisierte Prozesse ohne Benutzerinteraktion vorgesehen ist.

Beide Optionen haben ihre Vorteile: Der API Key ist einfacher zu verwenden, aber OAuth 2.0 bietet ein höheres Sicherheitsniveau, da es Schlüssel nicht im Klartext speichert, sondern einen Mechanismus für Zugriffstoken verwendet.

Erstellen von Zugangsdaten über API Key

Beginnen wir mit dem API Key. Dies ist die einfachste Authentifizierungsmethode und eignet sich für den grundlegenden API-Zugriff. Wichtig: Der API Key eignet sich nur für öffentliche Google Sheets-Tabellen. Für den Zugriff auf private Tabellen verwenden Sie OAuth 2.0.

Wählen Sie im Dropdown-Menü die Option „API Key“ aus.

Daraufhin öffnet sich das Fenster zur Schlüsselerstellung. Im Feld „Name“ vergeben Sie einen Namen für den Schlüssel. Die Option „Authenticate API calls through a service account“ lassen Sie deaktiviert, da sie für unsere Aufgaben nicht benötigt wird.

Im Bereich „Application restrictions“ wählen Sie „None“ (keine Einschränkungen), da FastReport .NET als lokale Desktop-Anwendung arbeitet.

Im Bereich „API restrictions“ wählen Sie „Restrict key“ (Schlüssel einschränken). Dies ist eine wichtige Sicherheitseinstellung. Nach der Auswahl erscheint eine Liste der verfügbaren APIs, in der Sie die Google Sheets API suchen und auswählen müssen. Dadurch wird verhindert, dass der Schlüssel für den Zugriff auf andere Google-Dienste missbraucht wird.

Nach der Konfiguration klicken Sie auf die Schaltfläche „Create“.

Erstellen von Zugangsdaten über OAuth Client ID

Der zweite Typ von Zugangsdaten ist die OAuth Client ID. Dies ist eine sicherere Methode, die das OAuth 2.0 Protokoll für die Autorisierung verwendet.

Wählen Sie im Dropdown-Menü „Create credentials“ die Option „OAuth client ID“. Geben Sie als Anwendungstyp „Desktop app“ an (da FastReport .NET als lokale Anwendung läuft) und vergeben Sie einen Namen für den Client. Nach der Erstellung zeigt das System die Client ID und das Client Secret an und bietet an, eine JSON-Datei mit diesen Daten herunterzuladen. Diese Zugangsdaten werden später für die Verbindung zu Google Sheets im FastReport Designer benötigt.

Die Anbindung an Google Sheets erfolgt über ein Plugin, das vor der Einrichtung kompiliert werden muss. Das Projekt befindet sich im Pfad „Extras\Core\FastReport.Data\FastReport.Data.GoogleSheets“.

Nach dem Kompilieren des Projekts binden Sie das Plugin in FastReport ein. Für die Arbeit im Berichtsdesigner fügen Sie die kompilierte DLL-Datei über das Einstellungsmenü hinzu:

Für die programmatische Integration fügen Sie die Assembly zu den Projektverweisen hinzu und registrieren die Verbindung mit dem folgenden Code bei der Initialisierung der Anwendung:

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

Eine detaillierte Beschreibung der Verbindungserstellung über Code befindet sich in der Datei readme.txt, die zusammen mit dem Plugin-Projekt ausgeliefert wird.

Um eine Verbindung zu erstellen, wechseln Sie zur Registerkarte „Daten“ und wählen Sie „Neue Datenquelle“. Klicken Sie im Assistentenfenster auf „Neue Verbindung“ und wählen Sie „Verbindung zu Google Sheets“.

Geben Sie im Feld „Tabellen-ID oder URL-Adresse“ die Tabellen-ID oder die vollständige URL an. Beispiel: Bei der URL https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms lautet die Tabellen-ID „1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms“.

• Die Option „Spaltenüberschriften aus der ersten Zeile“ verwendet die erste Zeile der Google Sheets-Tabelle als Spaltennamen.
• Die Option „Ausgeblendete Blätter hinzufügen“ fügt Blätter zur Auswahlliste hinzu, die in der Google Sheets-Oberfläche ausgeblendet sind.

Für die Autorisierung können Sie einfach auf „OK“ klicken. Falls keine gespeicherten Zugangsdaten vorhanden sind, öffnet sich automatisch das Autorisierungsformular. Alternativ öffnen Sie das Autorisierungsformular selbst durch Klicken auf die Schaltfläche „Anmelden“ und geben die Zugangsdaten manuell ein. Beachten Sie, dass die eingegebenen Daten erst nach dem Klicken auf „OK“ im Hauptformular überprüft werden.

Die Wahl der Autorisierungsmethode beeinflusst den weiteren Ablauf:

• Bei der Verbindung über einen API Key ist keine Autorisierung im Browser erforderlich. Der Schlüssel wird direkt in der Anfrage übermittelt. Diese Methode funktioniert jedoch nur mit öffentlichen Tabellen.
• Bei der Verbindung über OAuth 2.0 ist eine Autorisierung im Browser erforderlich. Diese Methode funktioniert sowohl mit öffentlichen als auch mit privaten Tabellen.

Wenn Sie OAuth 2.0 wählen, wird im Designer ein Hinweisfenster angezeigt, über das Sie den Vorgang abbrechen können:

Die Autorisierung im Browser läuft wie folgt ab: Im sich öffnenden Browserfenster melden Sie sich in dem Google-Konto an, dessen E-Mail-Adresse im Schritt der OAuth-Einrichtung zur Liste der Testbenutzer hinzugefügt wurde. Wenn Sie versuchen, sich mit einem anderen Konto anzumelden, das nicht in der Liste der Testbenutzer steht, erscheint eine Zugriffsfehlermeldung mit dem Hinweis, dass die Anwendung nur für Testbenutzer verfügbar ist.

Im nächsten Schritt erscheint eine Warnung, dass die Anwendung keine Google-Prüfung durchlaufen hat. Dies ist eine Standardmeldung für Anwendungen im Testmodus. Klicken Sie auf „Fortsetzen“, um den Zugriff zu gewähren.

Daraufhin wird der Bildschirm mit der Anfrage der Zugriffsrechte angezeigt. Dort steht, dass die Anwendung „FastReportNET“ die Berechtigung benötigt, alle Google Sheets-Tabellen anzuzeigen. Überprüfen Sie die angeforderten Rechte und klicken Sie auf „Fortsetzen“, um zu bestätigen.

Nach erfolgreicher Autorisierung öffnet sich ein Tab mit dem Text „Close the window“. Dies bedeutet, dass die Zugangsdaten erfolgreich gespeichert wurden und der Browser geschlossen werden kann.

Wechseln Sie zurück zum FastReport .NET Designer. Wenn die Verbindung erfolgreich war, wird im nächsten Fenster eine Liste der verfügbaren Tabellen aus Google Sheets angezeigt. Die folgenden Screenshots zeigen, wie sich die Liste der Felder ändert, abhängig von der Option „Spaltenüberschriften aus der ersten Zeile“:

• Wenn die Option aktiviert ist, wird die erste Zeile der Tabelle als Spaltennamen verwendet (z. B. Student Name, Gender usw.).
• Wenn die Option deaktiviert ist, erhalten die Spalten Standardnamen (Column1, Column2 usw.).

Daten aus Google Sheets werden in derselben Form importiert, in der sie in der Tabelle vorliegen, also als Text und Zahlen. Visuelle Objekte wie Bilder, Diagramme, Grafiken und Zeichnungen (Formen, Linien, Schaltflächen) werden vollständig ignoriert. Interaktive Objekte werden in Text umgewandelt: Kontrollkästchen (Checkboxen) werden als Text (true/false) dargestellt, und anstelle einer Dropdown-Liste wird der in Google Sheets angezeigte Wert übernommen.

Ein Beispiel für das Endergebnis der Arbeit mit Google Sheets in FastReport .NET: Die Daten, die erfolgreich aus der Cloud-Tabelle abgerufen wurden, werden im Bericht angezeigt.

In diesem Artikel wurde der Prozess der Anbindung des Google Sheets-Plugins an FastReport .NET ausführlich beschrieben – von der Einrichtung des API-Zugriffs über die Google Cloud Console bis hin zur abschließenden Autorisierung und dem Datenimport. Nach erfolgreicher Autorisierung werden die Daten aus Google Sheets korrekt in den Berichtsdesigner importiert, mit Ausnahme von visuellen und interaktiven Objekten, die entweder ignoriert oder in Textdarstellung umgewandelt werden.