Beispiel: Schreiben von Daten in Protocol Buffers
In diesem Beispiel wird gezeigt, wie Daten in im Protocol Buffers-Format kodierte Binärdateien geschrieben werden. Die Quelldaten in dieser Demo stammen aus einer SQLite-Datenbank (Nanonull.sqlite); Sie können Daten jedoch auf ähnliche Weise aus verschiedenen anderen von MapForce unterstützten Formaten, wie XML, EDI, JSON und anderen extrahieren.
In der Demo-Quelldatenbank sind Daten über Personen, deren Adressen und die Produkte, die sie in einem Geschäft bestellt haben, gespeichert. Aus der Datenbank sollen nun Bestellinformationen extrahiert werden und es sollen mehrere Binärdateien im Protocol Buffers-Format generiert werden. Für jede Bestellung soll eine Binärdatei mit der Erweiterung .dat generiert werden. Der Name der generierten Datei soll die eindeutige Bestell-ID, z.B. Order1.dat, Order2.dat, usw., enthalten. Außerdem soll jede Binärdatei die Bestell-ID, den Namen und die E-Mail Adresse der Person, das Datum und die Lieferadresse enthalten. Die .proto -Datei, die die Struktur einer solchen Bestellung beschreibt, sieht folgendermaßen aus:
syntax="proto3";
package mapforce.demo;
message Order { int32 id = 1; string name = 2; string email = 3; DateType entry_date = 4; // An order can have multiple addresses (shipping, billing) repeated AddressType address = 5; }
message DateType { // Must be from 1 to 9999 int32 year = 1; // Must be from 1 to 12 int32 month = 2; // Must be from 1 to 31, and valid for the year and month int32 day = 3; }
message AddressType { string city = 1; string street = 2; int32 number = 3; bool shipping = 5; bool billing = 4; } |
orders.proto
Sowohl die Datenbank Nanonull.sqlite als auch die Datei orders.proto steht im folgenden Verzeichnis zur Verfügung: <Dokumente>\Altova\MapForce2024\MapForceExamples\. Die Mapping-Design-Datei zur Durchführung der Transformation hat den Namen GenerateOrders.mfd und befindet sich im selben Verzeichnis. Sie können das Mapping öffnen und direkt ausführen oder die unten stehende Anleitung befolgen, um es von Grund auf neu zu erstellen.
GenerateOrders.mfd
Wie Sie oben sehen, besteht das Mapping aus einer Quellkomponente (der SQLite-Datenbank) und einer Zielkomponente (der Binärkomponente).
Beachten Sie, dass die Tabelle users unterhalb der Tabelle orders verschachtelt ist, da MapForce automatisch eine Sekundärschlüsselbeziehung zwischen diesen beiden Tabellen erkannt hat. Ebenso ist die Tabelle addresses unter users verschachtelt. Bei allen Verbindungen, die von solchen verschachtelten Tabellen gezogen werden, wird sichergestellt, dass die Schlüsselbeziehungen im Mapping beibehalten werden. Nähere Informationen dazu finden Sie unter Behandlung von Datenbankbeziehungen.
In der Zielkomponente sehen Sie am Datenelement Datei<dynamisch>, dass die Binärkomponente auf Basis der aus dem Mapping erhaltenen Informationen Instanzdateien dynamisch erstellt. Damit die Dateien der Zielkomponente dynamisch generiert werden, klicken Sie auf die Schaltfläche 
und aktivieren Sie im Kontextmenü die Option Über das Mapping bereitgestellte dynamische Dateinamen verwenden. Nähere Informationen zu dynamischen Dateinamen finden Sie unter Dynamische Verarbeitung mehrerer Input- oder Output-Dateien.
In diesem Mapping wird für jede id in der Datenbanktabelle orders eine neue Datei generiert, wie Sie an der Verbindung zum Datenelement Datei: <dynamisch> sehen. Die Namen der einzelnen generierten Dateien werden mit Hilfe der ersten concat-Funktion generiert. Diese Funktion verbindet den String "Order" mit der eindeutigen ID der Bestellung aus der Datenbank und der Dateierweiterung ".dat". Die generierten Dateien erhalten dadurch Namen wie Order1.dat, Order2.dat, usw.
Die concat-Funktion wird im Mapping auch ein zweites Mal aufgerufen. Dieses Mal ist ihr Ergebnis der Name der Person, der durch Verkettung des Vor- und Zunamens und Einfügen eines Leerzeichens dazwischen erstellt wird.
Die "GetDate"-Komponente in der Mitte schließlich ist eine benutzerdefinierte Funktion, die die Datenfelder in der Binärdatei befüllt. Diese Funktion erhält als Input ein Datum in String-Form, parst es und gibt Jahr, Monat und Tag separat in Form von Ganzzahlwerten zurück. Diese Konvertierung ist erforderlich, um das in der .proto-Datei definierte Datumsformat zu erhalten. Wenn Sie im Mapping auf die Titelleiste der Funktion doppelklicken, können Sie die Definition dieser Funktion anzeigen oder ändern.
Benutzerdefinierte Funktion "GetDate"
Wie oben gezeigt, parst die benutzerdefinierte Funktion "GetDate" den Input-Wert mit Hilfe der vordefinierten Funktion parse-dateTime. Die Maske [Y]-[M]-[D] [H]:[m]:[s] entspricht dem in der Datenbank gespeicherten Datenformat, z.B. 2017-10-19 08:09:54. Nähere Informationen zu Formatmasken finden Sie unter der Beschreibung der Funktion parse-dateTime. Als nächstes werden verschiedene vordefinierte Funktionen aufgerufen, um die relevanten Datumsteile aus den geparsten Daten zu extrahieren und zurückzugeben.
Erstellen des Mappings
Um das Mapping (oder ein ähnliches) von Grund auf neu zu erstellen, gehen Sie folgendermaßen vor:
1.Fügen Sie die Quelldatenbank hinzu.
2.Fügen Sie die .proto-Zieldatei ein, siehe Hinzufügen von Binärdateien zum Mapping.
3.Konfigurieren Sie die Zielkomponente so, dass die Dateinamen bei der Ausführung des Mappings dynamisch generiert werden. Klicken Sie dazu auf die Schaltfläche und wählen Sie im Kontextmenü die Option Über das Mapping bereitgestellte dynamische Dateinamen verwenden. Verbinden Sie als nächstes das Datenelement Datei<dynamisch> mit einem Input, der den Dateinamen bereitstellt. In diesem Beispiel wird der Dateiname, wie oben beschrieben, mit Hilfe der concat-Funktion erstellt. Nähere Informationen zu dynamischen Dateinamen finden Sie unter Dynamische Verarbeitung mehrerer Input- oder Output-Dateien.
4.Fügen Sie optional vordefinierte MapForce-Funktionen hinzu und verbinden Sie deren Inputs. In diesem Beispiel wird die concat-Funktion zwei Mal verwendet. Nähere Informationen dazu finden Sie unter Hinzufügen einer Funktion zum Mapping. Beachten Sie, dass bei Aufruf von vordefinierten Funktionen wie concat einige der Input-Daten wahrscheinlich aus String-Konstanten stammen. Informationen dazu, wie Sie solche Konstanten hinzufügen, finden Sie unter Hinzufügen einer Konstante zum Mapping.
5.Fügen Sie optional eventuell erforderliche benutzerdefinierte Funktionen hinzu. Mit Hilfe dieser Funktionen können einige der Mapping-Details wegabstrahiert werden, sodass Sie die Übersicht besser behalten. So konvertiert etwa die benutzerdefinierte Funktion "GetDate" in diesem Beispiel, wie erwähnt, einen String in Datumsteile, wobei ihre Implementierungslogik im Hauptmapping ausgeblendet wird. Nähere Informationen zum Erstellen von benutzerdefinierten Funktionen finden Sie unter Benutzerdefinierte Funktionen.
Wenn Sie mit MapForce noch gar nicht vertraut sind, finden Sie im Kapitel Tutorials einige einfache Schritt-für-Schritt-Beispiele.
Ausführen des Mappings
Wie zu Beginn dieses Beispiels erläutert, sollen mit dem Mapping mehrere .dat-Dateien erzeugt werden. Um eine Vorschau auf die generierten Dateien zu sehen, klicken Sie auf das Fenster Ausgabe.
Wie oben gezeigt, werden im Fenster Ausgabe alle generierten Dateien angezeigt. Durch Klicken auf die Richtungspfeile oder auf einen Eintrag aus der Liste können Sie darin navigieren. Um die generierte Ausgabe zu speichern, wählen Sie eine der folgenden Methoden:
•Klicken Sie im Menü Ausgabe auf Alle Ausgabedateien speichern. ( 
).
•Klicken Sie auf die Symbolleisten-Schaltfläche Alle generierten Ausgaben speichern ( ).
Wenn Sie mit MapForce eine Vorschau auf die Ausgabe-Binärdateien generieren, wird ihre Struktur im JSON-Format angezeigt, da dieses Format im Gegensatz zum Binärformat für Menschen lesbar ist. Durch Anzeige der Ausgabe im JSON-Format können Sie das Mapping testen. Wenn Sie die Ausgabedatei speichern, wird diese jedoch als Binärdatei gespeichert. |
Automatisierung mit MapForce Server
Wenn Sie MapForce Server lizenziert haben, können Sie das Mapping auch über die Befehlszeile auf einem Linux-, macOS- oder Windows-Rechner ausführen:
1.Kompilieren Sie das Mapping mit dem Menübefehl Datei | Zu MapForce Server-Ausführungsdatei kompilieren zu einer MapForce Server-Ausführungsdatei (.mfx), siehe auch Kompilieren von Mappings zu MapForce Server-Ausführungsdateien.
2.Kopieren Sie die .mfx-Datei auf den Server-Rechner.
3.Da in diesem Mapping Daten aus einer SQLite-Datenbankdatei ausgelesen werden, kopieren Sie die Datenbankdatei Nanonull.sqlite auf dem Server in dasselbe Verzeichnis wie die .mfx-Datei. Informationen zu anderen Datenbankarten finden Sie unter Datenbankmappings in verschiedenen Ausführungsumgebungen.
4.Führen Sie MapForce Server mit dem unten stehenden Befehl aus.
mapforceserver run GenerateOrders.mfx |
Anmerkungen:
•mapforceserver ist der betriebssystemspezifische Pfad zur ausführbaren MapForce Server-Datei.
•Ändern Sie den Pfad zur .mfx-Datei nach Bedarf oder kopieren Sie die .mfx-Datei in denselben Ordner wie die ausführbare Datei.
Sie können Mappings bei der Server-Ausführung als API-Aufruf oder als FlowForce Server-Auftrag (entweder bei Bedarf oder in regelmäßigen Abständen) ausführen. Nähere Informationen dazu finden Sie unter Automatisierung mit MapForce Server.