Bereitstellen eines Auftrags als Webservice
In diesem Beispiel wird beschrieben, wie Sie einen FlowForce Server-Auftrag erstellen, der als Webservice bereitgestellt wird. Dabei wird ein mit Altova MapForce erstelltes Mapping ausgeführt. Bei Aufruf des Webservice werden im Mapping Daten aus einer SQLite-Datenbank abgefragt und nur Datensätze, die mit einem als Parameter angegebenen Wert übereinstimmen, werden abgerufen. Hier wird beschrieben, wie Sie das vorhandene Mapping von MapForce aus auf FlowForce Server bereitstellen und zu einem Webservice machen. Nach Fertigstellung dieses Beispiels können Sie den Webservice über einen Browser aufrufen.
Voraussetzungen
•Benötigte Lizenzen: MapForce Enterprise oder Professional Edition, MapForce Server oder MapForce Server Advanced Edition, FlowForce Server
•Der FlowForce Web Server- und der FlowForce Server-Dienst werden an der konfigurierten Netzwerkadresse und am konfigurierten Port ausgeführt und sind dort empfangsbereit.
•Sie haben ein FlowForce Server-Benutzerkonto mit Berechtigungen für einen der Container (standardmäßig hat jeder authentifizierte Benutzer Zugriff auf den in diesem Beispiel verwendeten Container /public).
•Mit dem in diesem Beispiel erstellten Mapping-Auftrag wird eine XML-Datei in ein lokales Verzeichnis geschrieben. Auf dem Betriebssystem, auf dem FlowForce Server läuft, muss daher ein Verzeichnis vorhanden sein, in das die Auftragsausgabe geschrieben werden kann. In diesem Beispiel wird C:\FlowForceExamples\GetPersonRecords verwendet.
•Im Auftrag in diesem Beispiel werden Daten aus einer SQLite-Datenbank gelesen. Dazu müssen keine Datenbanktreiber installiert werden. Wenn Sie allerdings eine andere Datenbank verwenden möchten, müssen die Datenbanktreiber nicht nur auf dem Rechner, auf dem das Mapping erstellt wird, sondern auch auf dem Server, auf dem der Auftrag ausgeführt wird, installiert werden. So muss etwa im Fall von Microsoft Access-Datenbanken Microsoft Access Runtime (https://www.microsoft.com/en-us/download/details.aspx?id=50040) auf dem Rechner, auf dem FlowForce Server ausgeführt wird, installiert sein.
Verwendete Demo-Dateien
In diesem Beispiel werden die folgenden Dateien verwendet. Sie finden die Dateien auf dem Rechner, auf dem MapForce installiert ist, unter dem folgenden Pfad: ..\Dokumente\Altova\MapForce2025\MapForceExamples\Tutorial.
•FilterDatabaseRecords.mfd (die MapForce Mapping-Design-Datei)
•Nanonull.sqlite (die SQLite-Datenbank, aus der die Daten ausgelesen werden).
Funktionsweise des Mappings
Das in diesem Beispiel beschriebene Mapping hat den Namen FilterDatabaseRecords.mfd und steht im Ordner "Tutorial" von MapForce (..\Dokumente\Altova\MapForce2025\MapForceExamples\Tutorial) zur Verfügung.
Wie oben beschrieben, ist die Quellkomponente eine Datenbank, in der Benutzerdatensätze gespeichert sind. Die Zielkomponente ist eine XML-Datei. Durch die Verbindung von users mit row wird für jeden aus der Quelldatei extrahierten Datensatz eine Zeile erstellt. Außerdem enthält das Mapping einen zur Laufzeit bereitgestellten Input-Parameter. Doppelklicken Sie auf die Titelleiste des Input-Parameters, um seine Eigenschaften anzuzeigen:
Des Weiteren enthält das Mapping zwischen der Quell- und der Zielkomponente eine SQL WHERE-Komponente. Die Aufgabe der SQL WHERE-Komponente ist es, nur die Datenbankdatensätze an die Zielkomponente zu übergeben, die mit der Bedingung last_name LIKE :sqlparam übereinstimmen. Auch dies wird über die Komponenteneigenschaften konfiguriert:
Der Wert von :sqlparam wird durch Verkettung des Input-Parameters mit dem Zeichen % erzeugt. Wenn also beim Aufruf des Auftrags zur Laufzeit der Input-Parameter "m" bereitgestellt wird, ruft das Mapping Benutzerdatensätze, deren Nachname mit "m" beginnt, auf.
Nähere Informationen zum Erstellen von Mappings wie des in diesem Beispiel beschriebenen finden Sie in der Dokumentation zu MapForce (https://www.altova.com/de/documentation).
Vorbereiten des Mappings für die Bereitstellung auf FlowForce Server
Mit "Quellrechner" wird in der Anleitung unten der Computer bezeichnet, auf dem MapForce installiert ist und mit "Zielrechner" wird der Computer bezeichnet, auf dem FlowForce Server installiert ist (Dies kann, muss aber nicht, derselbe Rechner sein).
Bevor Sie versuchen, das Mapping auf dem Zielrechner bereitzustellen, gehen Sie folgendermaßen vor:
1.Stellen Sie sicher dass der "FlowForce Web Server"-Dienst als für HTTP(S) Requests empfangsbereit konfiguriert wurde, siehe Definieren der Netzwerkeinstellungen. Wenn FlowForce Server z.B. auf demselben Rechner installiert ist und mit den Standardeinstellungen konfiguriert wurde, sollte er im Browser durch Eingabe von http:/localhost:8082 aufgerufen werden können. Wenn FlowForce Server auf einem anderen Rechner läuft, stellen Sie sicher, dass die eingehenden Daten für die angegebene Adresse und den angegebenen Port nicht durch eine Firewall blockiert werden.
2.Stellen Sie sicher, dass auch der "FlowForce Server"-Dienst als für HTTP(S) Requests empfangsbereit konfiguriert wurde. Dieser Dienst behandelt Requests für Aufträge, die als Webservices bereitgestellt wurden , siehe auch Funktionsweise. Wenn der Webservice auch von HTTP-Clients von außerhalb des lokalen Host-Rechners aufgerufen werden können soll, muss der "FlowForce Server"-Dienst folglich auch entweder an allen Schnittstellen oder an einer bestimmten Adresse, die nicht die des lokalen Host ist, empfangsbereit sein. Ob dieser Dienst richtig konfiguriert ist, können Sie durch Aufruf der folgenden URL über den Browser überprüfen: http(s)://<host or IP address><port>/service/ . Wenn Sie aufgefordert werden, ein Passwort einzugeben, geben Sie das Passwort für Ihr FlowForce Server-Benutzerkonto an. Alle etwaigen als Webservices bereitgestellte Aufträge sollten direkt im Browser-Fenster als Links angezeigt werden.
3.Stellen Sie folgendermaßen sicher, dass im Mapping relative Pfade anstelle von absoluten verwendet werden:
a)Öffnen Sie das Mapping FilterDatabaseRecords.mfd in MapForce, klicken Sie mit der rechten Maustaste in den Mapping-Bereich und wählen Sie im Kontextmenü den Befehl Mapping-Einstellungen aus.
b)Deaktivieren Sie gegebenenfalls das Kontrollkästchen Pfade im generierten Code absolut machen.
Anmerkung: | Das Kontrollkästchen Windows-Pfadkonvention ... verwenden ist bei Mappings in der BUILT-IN-Sprache, wie dem Mapping in diesem Beispiel, nicht anwendbar. Dieses Kontrollkästchen wird nur angewendet, wenn die Mapping-Sprache entweder XSLT oder XQuery ist. |
c)Speichern Sie das Mapping.
Dateibasierte Datenbanken wie Microsoft Access oder SQLite werden nicht zusammen mit dem Mapping auf dem Zielrechner bereitgestellt. Die Access-Datenbank muss daher manuell vom Quell- auf den Zielrechner kopiert werden. Kopieren Sie die Datenbankdatei Nanonull.sqlite aus dem Verzeichnis ..\Dokumente\Altova\MapForce2025\MapForceExamples\Tutorial des Quellrechners in ein leeres Verzeichnis auf dem Zielrechner. Das Zielverzeichnis in diesem Beispiel ist C:\FlowForceExamples\GetPersonRecords. Notieren Sie sich diesen Pfad, da er später vom FlowForce-Auftrag referenziert wird.
Das Mapping kann nun auf FlowForce Server bereitgestellt werden. Nähere Informationen zum Bereitstellen von Mappings mit Datenbankverbindungen finden Sie unter Vorbereiten von Mappings für die Server-Ausführung.
Bereitstellen des Mappings
So stellen Sie das Mapping auf FlowForce Server bereit:
1.Klicken Sie im Menü Datei auf Auf FlowForce Server bereitstellen. Wenn Sie das Mapping auf einem FlowForce Server auf einem anderen Rechner bereitstellen möchten, ändern Sie die Server-Adresse und den Port von "localhost:8082" in die die über die FlowForce Server-Netzwerkeinstellungen konfigurierten Einstellungen.
2.Aus Gründen der Einheitlichkeit stellen wir das Mapping wie die anderen Beispiele im Container /public/Examples bereit. Klicken Sie auf Durchsuchen und ändern Sie den Container-Pfad in /public/Examples. Der Container /public/Examples muss bereits vorhanden sein, wenn Sie das vorherige Beispiel durchgearbeitet haben; Andernfalls können Sie ihn durch Klick auf Container erstellen erstellen.
3.Aktivieren Sie das Kontrollkästchen Web Browser zur Erstellung eines neuen Auftrags öffnen.
4.Klicken Sie auf OK.
Nähere Informationen zu allen Einstellungen für die Bereitstellung eines Mappings Bereitstellen von Mappings auf FlowForce Server.
Erstellen des FlowForce-Auftrags
Sie haben das Mapping jetzt auf FlowForce Server bereitgestellt und die Auftragskonfigurationsseite im Browser geöffnet (vorausgesetzt Sie haben das Kontrollkästchen Web Browser zur Erstellung eines neuen Auftrags öffnen im Dialogfeld oben aktiviert). Melden Sie sich andernfalls auf der FlowForce Server Web-Verwaltungsschnittstelle an, öffnen Sie die zuvor bereitgestellte Mapping-Funktion (die sich im Container /public/Examples befinden sollte) und klicken Sie auf Auftrag erstellen.
So konfigurieren Sie den Auftrag:
1.Erstellen Sie unter "Auftrags-Input-Parameter" einen neuen Input-Parameter vom Typ String. Dieser Wert wird beim Aufruf des Auftrags über den Webservice bereitgestellt. Nennen Sie den Parameter "LookupValue".
2.Konfigurieren Sie die folgenden Ausführungsschritte:
•Setzen Sie den Wert des Input-Parameters auf den im vorherigen Schritt erstellten Input-Parameter "LookupValue".
•Setzen Sie den Arbeitsverzeichnis auf C:\FlowForceExamples\GetPersonRecords. Beachten Sie, dass dieses Verzeichnis im Dateisystem bereits vorhanden sein muss und die Quelldatenbank Nanonull.sqlite bereits enthalten sollte, wenn Sie die vorherigen Schritte durchgeführt haben.
3.Um den Auftrag in einen Webservice umzuwandeln, aktivieren Sie das Kontrollkästchen Diesen Auftrag über HTTP unter URL zur Verfügung stellen und geben Sie den Namen des Webservice ein, zum Beispiel:
Notieren Sie sich den Namen des Diensts; Sie benötigen diesen, um den Webservice aufzurufen.
4.Wählen Sie unter "Anmeldeinformationen" einen vorhandenen Eintrag aus oder definieren Sie lokale Anmeldeinformationen.
Anmerkung: | Es handelt sich hierbei um die Anmeldeinformationen für Ihr Benutzerkonto auf dem Betriebssystem und nicht um die Anmeldeinformationen für den Aufruf der FlowForce Server Web-Verwaltungsschnittstelle. Über dieses Benutzerkonto müssen Sie Zugriff auf die Datenbankdatei Nanonull.sqlite aus dem Arbeitsverzeichnis haben, da der Auftrag sonst nicht erfolgreich ausgeführt werden kann. |
5.Klicken Sie auf Speichern.
Aufruf des Webservice
Sie haben die Auftragskonfiguration nun abgeschlossen. Da dieser Auftrag als Webservice bereitgestellt wird, können Sie ihn auf jede der folgenden Arten ausführen:
•Gehen Sie zur Startseite und klicken Sie anschließend auf Alle aktiven Trigger und Dienste anzeigen. Klicken Sie anschließend auf die in der Spalte "Info" angezeigte URL des Auftrags.
•Geben Sie in die Adressleiste des Browsers http://127.0.0.1:4646/service/GetPersonRecordsService ein. Beachten Sie, dass diese URL nur funktioniert, wenn der FlowForce Server-Dienst an der Standard-Host-Adresse und am Standard-Port-Namen empfangsbereit ist. Wenn Sie auf der Setup-Seite andere Host- und Port-Einstellungen definiert haben, dann ändern Sie die Adresse entsprechend.
•Wenn Sie das optionale Feld Host-Name von FlowForce Server auf der Setup-Seite definieren, können Sie den Webservice-Aufruf direkt über die Auftragskonfigurationsseite ausführen, indem Sie neben dem Kontrollkästchen Diesen Auftrag über HTTP...zur Verfügung stellen auf die Schaltfläche klicken. Andernfalls wird diese Schaltfläche nicht angezeigt.
Wenn Sie beim Aufrufen des Web-Diensts nach Anmeldeinformationen gefragt werden, so geben Sie dieselben Anmeldeinformationen ein, mit denen Sie sich auch bei FlowForce Server angemeldet haben.
Achtung Für die HTTP-Authentifizierung sollten Sie Ihre FlowForce Server-Anmeldeinformationen nur zu Testzwecken eingeben. Für Produktionszwecke wird empfohlen, einen neuen FlowForce-Benutzer zu erstellen, diesem Benutzer im Container, in dem sich der Auftrag befindet, die Berechtigung Dienst - Verwenden einzuräumen und den Web-Dienst anschließend über das entsprechende Benutzerkonto aufzurufen. Um die HTTP-Authentifizierung zu deaktivieren, und den Web-Dienst öffentlich zugänglich zu machen, weisen Sie dem Benutzer Anonymous die Berechtigung Dienst - Verwenden zu. Nähere Informationen, siehe Funktionsweise von Berechtigungen. |
Da dieser Auftrag Parameter hat, werden Sie aufgefordert, einen Parameterwert anzugeben, wenn Sie den Webservice in einem Browser aufrufen.
Wenn Sie einen gültigen Verzeichnispfad wie z.B. M eingeben, wird im Auftrag die Datenbank abgefragt und Sie erhalten nur die Zeilen für die Personen, deren Nachnamen mit "M" beginnen, z.B:
Bei einem Fehler wird im Browser der Fehler "Dienstausführung fehlgeschlagen" angezeigt. Wenn Sie diesen Fehler sehen, überprüfen Sie das Auftrags-Log auf weitere Informationen.