Erstellen von SOAP-Webservice-Projekten anhand von WSDL-Dateien
In diesem Beispiel wird gezeigt, wie Sie einen SOAP-Webservice in MapForce erstellen. Sie finden das Mapping-Projekt zu diesem Beispiel unter dem folgenden Pfad: <Dokumente>\Altova\MapForce2023\MapForceExamples\Query Person database.mfp. Ziele in diesem Beispiel:
•Abrufen einer Gruppe von Personendatensätze anhand einiger Kriterien mittels SOAP-Request aus einer SQLite-Datenbank auf einem Server. (Die Abfrage wird zur Laufzeit am Cient eingegeben und anschließend an den Server gesendet. Der Server sendet anschließend eine XML-Antwort mit den Suchergebnissen zurück).
•Einfügen neuer Datensätze in die SQLite-Datenbank, ebenfalls mittels SOAP Requests. (Die Personendaten werden im SOAP-Request angegeben. Bei Erfolg sendet der Server eine Bestätigung zurück, dass die Personendaten erfolgreich zur Datenbank hinzugefügt wurden.)
Bitte beachten Sie die folgenden Punkte:
•Das Mapping, mit dem der Webservice in MapForce generiert wird, hängt nicht von der Ziel-Programmiersprache ab, d.h. es ist identisch, egal ob Java- oder C#-Webservices generiert wird. Der Unterschied entsteht erst beim Kompilieren und Bereitstellen des Webservice auf dem Webserver, wie später in dieser Dokumentation beschrieben.
•Um SOAP-Beispiel-Requests zu generieren, um eine Vorschau auf die Mapping-Ausgabe anzeigen zu können, wird in diesem Beispiel die XMLSpy Enterprise Edition verwendet. Die WSDL-Quelldatei in diesem MapForce-Projekt wurde ebenfalls mit XMLSpy erstellt (und kann damit auch validiert werden). Webservices können auch ohne XMLSpy in MapForce erstellt werden. In diesem Fall benötigen Sie jedoch einen SOAP-Client, der in der Lage ist, SOAP-Requests anhand von WSDL-Dateien zu generieren.
Erstellen eines Webservice-Projekts
Wie bereits erwähnt, benötigen Sie zur Erstellungen eines SOAP-Webservice mit MapForce eine WSDL-Datei. Wir verwenden in diesem Beispiel einer WSDL-Datei, die mit der XMLSpy Enterprise Edition erstellt wurde. In der Abbildung unten sehen Sie die WSDL-Struktur, wie sie in der WSDL-Ansicht von XMLSpy angezeigt wird. Beachten Sie, dass darin zwei Operationen (getPerson und putPerson) für die oben angegebene Zwecke definiert sind.
| Anmerkung: | Die WSDL-Datei muss gültig sein, damit Sie anhand dieser Datei ein MapForce Webservice-Projekt erstellen können. |
So erstellen Sie anhand dieses Webservice ein Webservice-Projekt:
| 1. | Wählen Sie im Menü Datei den Befehl Neu und wählen Sie "Webservice-Projekt" aus. |
 |
| 2. | Navigieren Sie im Ordner <Dokumente>\Altova\MapForce2023\MapForceExamples\ zur Datei query.wsdl. Nach Auswahl der WSDL-Datei werden die restlichen Felder automatisch ausgefüllt. |
| 3. | Klicken Sie auf OK. |
| 6. | Geben Sie den Namen des WSDL-Projekts ein, wenn Sie dazu aufgefordert werden und klicken Sie auf Speichern. |
Im Projektfenster sehen Sie das Projekt und den WSDL-Namen sowie die einzelnen in der WSDL-Datei definierten Operationen. Die beiden Operationen sind getPerson und putPerson.
Erstellen der Operation "getPerson"
Doppelklicken Sie im Projektfenster auf die Datei getPerson.mfd, um deren Inhalt im Hauptbereich zu laden. Die getPersonSoapIn-Komponente enthält das Datenelement query, mit Hilfe dessen die Datenbank über den Webservice abgefragt werden soll. Die getPersonSoapOut-Komponente enthält die in der WSDL-Datei definierte Person-Struktur.
Wählen Sie Einfügen | Datenbank und fügen Sie die SQLite-Datenbank people.sqlite aus dem Ordner <Dokumente>\Altova\MapForce2023\MapForceExamples\ zum Mapping-Bereich hinzu. Die Datenbank enthält nur eine Tabelle, Persons, deren Felder mit denen in der Komponente getPersonSoapOut übereinstimmen. Nähere Informationen zum Hinzufügen von Datenbanken als Mapping-Komponenten finden Sie unter Datenbanken und MapForce. Ziehen Sie Verbindungen zwischen den Komponenten, wie unten gezeigt:
Das oben gezeigte Mapping-Design ist noch nicht fertig, Sie sehen aber schon, was zur Laufzeit geschieht. Die Verbindung zwischen part:Query und part:Result stellt den Webservice-Aufruf dar. Das Datenelement part:Query der Komponente getPersonSoapIn ist der Platzhalter für die Abfrage (hier wird der Abfragestring in den SOAP-Client eingegeben). Über die Verbindungen zwischen der Datenbanktabelle und dem Datenelement Person der getPersonSoapOutput-Komponente werden Werte aus den entsprechenden Datenbankfeldern extrahiert und an die entsprechenden Datenelemente in der Zielkomponente übergeben. Sie können bereits schnell eine Vorschau auf die Ausgabe anzeigen. Gehen Sie dazu folgendermaßen vor:
1.Klicken Sie mit der rechten Maustaste auf die Komponente getPersonSoapInput und wählen Sie im Kontextmenü den Befehl Eigenschaften.
2.Klicken Sie auf Durchsuchen und wählen Sie den folgenden Beispiel-Request aus: <Dokumente>\Altova\MapForce2023\MapForceExamples\getPersonRequest.xml.
3.Klicken Sie auf OK.
4.Klicken Sie auf das Fenster Ausgabe.
Zu diesem Zeitpunkt werden alle Datensätze aus der Datenbanktabelle extrahiert, was nicht sehr hilfreich ist. Wir müssen daher einen Filter hinzufügen und nur die Datenelemente extrahieren, die dem Request-String entsprechen.
1.Fügen Sie die Funktion concat durch Ziehen aus dem Fenster "Bibliotheken" zum Mapping-Bereich hinzu. Mit Hilfe dieser Funktion werden die Vor- (First) und Nachnamen (Last)der einzelnen Personen miteinander verkettet.
2.Klicken Sie im Menü Einfügen auf Konstante und fügen Sie eine Konstante bestehend aus einem Leerzeichen hinzu. Die Konstante liefert das Leerzeichen zwischen dem aus der Datenbank extrahierten Vor- und Nachnamen.
3.Fügen Sie die Funktion contains durch Ziehen aus dem Fenster "Bibliotheken" in den Mapping-Bereich hinzu.
4.Klicken Sie mit der rechten Maustaste auf die Verbindung zwischen der Quelltabelle Persons und dem Ziel-Node Person und wählen Sie im Kontextmenü den Befehl Filter einfügen: Nodes/Zeilen.
| 7. | Ziehen Sie Verbindungslinien zwischen den Komponenten, wie unten gezeigt. |
"getPerson" Mapping
Wie oben gezeigt, gibt die Funktion contains true zurück, wenn ein ganzer Name oder ein Teil eines Namens einer Person in der Datenbank mit dem Abfragestring übereinstimmt ("name" wird dabei von der concat Funktion bereitgestellt und besteht aus dem Vornamen (first), gefolgt von einem Leerzeichen und anschließend dem Nachnamen (last)). Wenn eine Übereinstimmung gefunden wird, werden die Details der gefundenen Person in die Response-Nachricht inkludiert. So würden etwa bei Eingabe von "Ro" in diesem Beispiel die folgenden Datensätze zurückgegeben: "Martin Rope", "Ronald Superstring", "Robert Darkmatter" und "Roger Gravity".
Erstellen der Operation "putPerson"
Doppelklicken Sie im Projektfenster auf die Datei putPerson.mfd, um ihren Inhalt in den Hauptbereich zu laden. Die Komponente putPersonSoapInput stellt die Request-Struktur (die Datenelemente, die über den Webservice in die Datenbank eingefügt werden) zur Verfügung. Die Komponente putPersonSoapOutput repräsentiert das Ergebnis des Webservice-Aufrufs. Sie enthält einen Bestätigungsteil (part: Confirmation), in dem das Ergebnis des Webservice-Aufrufs angezeigt wird.
Gehen Sie vor, wie oben beschrieben, um die folgenden Komponenten zum Mapping hinzuzufügen:
•die SQLite-Datenbank people.sqlite (Hier werden die durch den Webservice-Aufruf abgerufenen Daten eingefügt)
•die Funktion concat und fünf Konstanten (Damit wird der Bestätigungsstring erstellt, der dem Aufrufer des Webservice angezeigt wird)
Ziehen Sie die Verbindungen wie unten gezeigt:
"putPerson"-Mapping
Im oben gezeigten Mapping wird die Datenbank aufgrund der Verbindung zwischen part: Put und der Datenbank zur Laufzeit aktualisiert. Auf Seite der Zielkomponente wird die part: Confirmation Response durch Verkettung verschiedener Felder aus dem Request sowie von durch die Konstanten bereitgestelltem Text erzeugt. Nähere Informationen zu Mappings, mit denen Datenbanken aktualisiert werden, finden Sie unter Mappen von Daten auf Datenbanken.
So zeigen Sie eine Vorschau auf das Mapping an:
1.Klicken Sie mit der rechten Maustaste auf die Komponente putPersonSoapInput.
2.Klicken Sie auf Durchsuchen und wählen Sie den folgenden Beispiel-Request aus: <Dokumente>\Altova\MapForce2023\MapForceExamples\putPersonRequest.xml.
3.Klicken Sie auf das Fenster Ausgabe.
Wenn Sie eine Vorschau auf das Mapping anzeigen, generiert MapForce die INSERT-Abfrage, mit der die Datenbank aktualisiert wird und zeigt sie im Fenster Ausgabe an, führt aber die tatsächliche Aktualisierung nicht durch. Um die Abfrage an der Datenbank auszuführen, wählen Sie den Menübefehl Ausgabe | SQL-Script ausführen.
Wenn der kompilierte Webservice jedoch auf einem Server bereitgestellt wird und von einem Client aufgerufen wird, wird die Datenbank sofort aktualisiert. Siehe auch Ausführen von Mappings, die Datenbanken modifizieren.
Anzeige einer Vorschau auf die Mapping-Ausgabe
Sie können in MapForce eine Vorschau von Mappings, die anhand von WSDL-Dateien erstellt wurden, anzeigen, bevor Sie diese auf einem Webserver bereitstellen. Zur Anzeige einer Vorschau auf ein solches Mapping benötigen Sie einen SOAP-Beispiel-Request (XML-Datei), der der WSDL-Datei entspricht. Sie können entweder mit XMLSpy oder einem anderen SOAP-Client Ihrer Wahl einen SOAP-Beispiel-Request für jede einzelne Operation (Mapping) in Ihrem Webservice-Projekt erstellen. In XMLSpy können Sie den Request mit dem Menübefehl SOAP | Neuen SOAP erzeugen generieren. Wenn neben MapForce auch XMLSpy installiert ist, können Sie direkt von MapForce aus einen Beispiel-Request generieren, z.B.:
1.Klicken Sie mit der rechten Maustaste auf die getPersonSoapInput-Komponente des Mappings und wählen Sie im Kontextmenü den Befehl Eigenschaften.
2.Klicken Sie auf Erstellen.
3.Speichern Sie die XML-Datei in einem Ordner auf Ihrem Rechner, wenn Sie dazu aufgefordert werden.
Die Request-Datei wird mit Dummy-Input-Werten (z.B. "String") anstelle der Input-Parameter erstellt. Bevor Sie die Request-Datei verwenden, müssen Sie die Dummy-Werte durch die gewünschten Request-Werte ersetzen. Für dieses Projekt stehen zwei Beispiel-Requests zur Verfügung:
1.<Dokumente>\Altova\MapForce2023\MapForceExamples\getPersonRequest.xml. Verwenden Sie diese Datei, um eine Vorschau auf die Ausgabe des Mappings getPerson zu sehen. Standardmäßig stellt die Datei den Wert "Ro" als Input für den Webservice bereit. Damit werden aus der Datenbank alle Personendatensätze, deren Vor- oder Nachname den Text "Ro" enthält, abgerufen.
2.<Dokumente>\Altova\MapForce2023\MapForceExamples\putPersonRequest.xml. Verwenden Sie diese Datei, um eine Vorschau auf die Ausgabe des Mappings putPerson zu sehen. Standardmäßig stellt diese Request-Datei die Personendaten einer fiktiven Person als Input für den Webservice bereit.
Um bei der Mapping-Vorschau andere Ausgaberesultate zu erhalten, bearbeiten Sie die beiden obigen Dateien, sodass sie die gewünschten Input-Werte enthalten.
Nächste Schritte
Sie sind nun bereit, um Code zu generieren, der den Webservice implementiert (entweder Java oder C#), ihn kompiliert und auf einem Server bereitstellt, wie in den folgenden Beispielen beschrieben: