Webservice-Aufrufe
Zu den generischen Webservices (nicht WSDL-Webservices) gehört eine große Kategorie von Webservices, die von ihrer Architektur her einem Stil namens "REST" entsprechen bzw. teilweise entsprechen. Diese Art von Webservices wird normalerweise als RESTful oder REST-Webservices bezeichnet. Generische HTTP-Webservices übertragen normalerweise in ihrem Message Body benutzerdefinierte Request- oder Response-Strukturen. MapForce unterstützt die folgenden Arten von Request- oder Response-Bodies: JSON, XML, Protocol Buffers und unstrukturierte Bodys, die benutzerdefinierte MIME Types enthalten. Aus der Sicht von MapForce hängen die Voraussetzungen, um einen Webservice aufrufen zu können vom Request-Typ ab:
•Im Fall von XML- oder JSON-Requests oder Responses benötigt MapForce die Request- oder Response-Struktur als JSON-, XML-, oder DTD-Schema. MapForce akzeptiert als Struktur auch eine XML-Datei mit einer gültigen Schemareferenz. Die Struktur des Webservice kann vom Anbieter des Webservice in Form eines XML- oder JSON-Schemas oder in einer formalen Sprache wie WADL oder auch in Form einer vom Menschen lesbaren Spezifikation zur Verfügung gestellt werden. Wenn Sie das XML- oder JSON-Schema des Request/Response bereits zur Verfügung haben, lässt sich der Webservice-Aufruf am leichtesten erstellen. Wenn Sie die Webservice-Definition als WADL-Datei haben, können Sie die benötigten Informationen aus der WADL-Datei importieren und etwaige Anpassungen manuell vornehmen. Beachten Sie jedoch, dass WADL keine Standardmethode zum Definieren von JSON-Strukturen, sondern nur zum Definieren von XML-Strukturen bietet. Wenn Sie schließlich eine XML- oder JSON-Beispielinstanzdatei, nicht aber die Schema-Datei haben, können Sie das Schema mit XMLSpy entweder erstellen oder generieren (https://www.altova.com/de/xmlspy.html). Falls nötig, kann XMLSpy Ihre Instanzdatei auch von XML in JSON konvertieren oder umgekehrt.
•Im Fall von Protocol Buffers Requests oder Responses benötigen Sie die .proto-Datei, die die Protocol Buffers-Binärdatei beschreibt. In diesem Szenario kann der Body des Webservice von oder auf eine Protocol Buffers-Komponente gemappt werden. Nähere Informationen dazu finden Sie unter Beispiel: Auslesen von Daten aus Protol Buffers und Beispiel: Schreiben von Daten in Protocol Buffers.
•Sie können auch Webservices aufrufen, bei denen die Request- oder Response-Struktur flexibel und nicht an ein bestimmtes Schema gebunden ist. ie können für solche Fälle die vordefinierten MapForce mime-Funktionen verwenden, um entweder den an den Webservice gesendeten Raw Message Body (die MIME Entity) zu erstellen oder die vom Webservice retournierte MIME Entity über das Mapping zu verarbeiten.
Hinzufügen eines Aufrufs zu einem generischen Webservice
1.Klicken Sie im Menü Einfügen auf Webservice-Funktion. (Klicken Sie alternativ dazu in der Symbolleiste auf die Schaltfläche Webservice-Funktion einfügen 
).
2.Klicken Sie unter Service-Definition auf Manuell.
3.Wenn Sie die WADL-Datei, in der der Service beschrieben ist, zur Verfügung haben, haben Sie auch die Möglichkeit, auf die Schaltfläche Aus WADL-Datei importieren zu klicken und die Datei auszuwählen (siehe Importieren von Webservice-Informationen aus einer WADL-Datei).
4.Wählen Sie die HTTP Request-Methode aus, mit der MapForce den Webservice aufrufen soll. Sie können entweder einen Wert aus der vorhandenen Liste auswählen oder den Namen der Request-Methode eingeben. Beachten Sie bei den Namen der HTTP-Methoden die Groß- und Kleinschreibung.
5.Wählen Sie eine der folgenden Methoden:
a.Geben Sie die URL des Webservice in das Textfeld URL ein. Bei dieser Methode haben Sie die Möglichkeit, bestimmte Teile der URL in Parameter zu verwandeln und diese über das Hauptmapping bereitzustellen. Beachten Sie bei auf diese Art definierten URLs Folgendes:
i.Wenn Sie einen Webservice mit "Vorlagen-" oder "Matrix"-Parametern aufrufen, setzen Sie die Parameter in geschweifte Klammern, z.B.: http://example.org/api/products/{id}. Definieren Sie anschließend die eigentlichen Einstellungen der einzelnen Parameter in der Tabelle "Parameter". MapForce verarbeitet die Parameternamen innerhalb geschweifter Klammern zur Laufzeit und erzeugt die endgültige URL, die die tatsächlichen Werte enthält.
ii.Wenn Sie einen Webservice mit URL-"Abfrageparametern" (z.B. http://example.org/api/products?sort=asc&category=1&page=1) aufrufen, geben Sie den Abfrageteil nicht in das URL-Textfeld ein, sondern definieren die Parameter nur in der Tabelle "Parameter" und stellen Sie sicher, dass diese als "Abfrage"-Parameter definiert sind.
iii.Ein Beispiel dazu finden Sie unter Definieren von Webservice-Parametern.
b.Wenn Sie die vollständige URL des Webservice über das Hauptmapping (oder eventuell als Parameter für das Mapping) bereitstellen möchten, aktivieren Sie das Kontrollkästchen Dynamische URL (wird durch Mapping bereitgestellt). Dadurch wird das Textfeld URL deaktiviert. In diesem Fall müssen Sie die vollständige URL des Webservice (einschließlich aller URL-Parameter) über das Hauptmapping erstellen und diese mit dem entsprechenden für die Webservice-Komponente angezeigten Input verbinden. Beachten Sie, dass es bei dieser Methode außer für Header-Parameter nicht mehr sinnvoll ist, Parameter in der Tabelle "Parameter" zu definieren. Wenn Sie dies versuchen, wird ein Dialogfeld angezeigt, in dem Sie darauf hingewiesen werden.
Dynamische URLs Sie können die URL mit beiden oben beschriebenen Methoden (vollständig oder teilweise dynamische URLs) flexibel, wie benötigt, anpassen. So könnten Sie das Mapping etwa in der Entwicklungsphase mit einer bestimmten URL ausführen und in der Produktion eine andere URL verwenden, ohne das Mapping ändern zu müssen. Bei einer URL wie https://{host}/some/path/to/service wäre dies möglich, vorausgesetzt, der Host-Name ist der einzige Unterschied zwischen der Produktions- und der Test-URL und Sie stellen diese als Parameter für das Mapping bereit. Beachten Sie, dass durch teilweise dynamische URLs eine strengere Validierung erzwungen wird, da nur die designierten URL-Teile durch mapbare Werte oder Laufzeitwerte ersetzt werden.
Bei vollständig dynamischen URLs ist die gesamte URL mapbar und Sie haben vollständige Kontrolle darüber. Die einzige Voraussetzung ist, dass die URL mit http:// oder https:// beginnt und es sich um eine gültige URI handeln muss. Bei dynamischen URLs kann außerdem die von einem Webservice-Aufruf retournierte URL als Input für eine andere Komponente, die denselben (oder einen anderen) Webservice aufrufen kann, bereitgestellt werden. |
6.Geben Sie unter Timeout optional eine Zeitspanne in Sekunden ein, nach der die Verbindung beendet werden soll, wenn der Server nicht antwortet.
7.Wenn für die HTTP-Methode ein Body-Teil (wie XML, JSON und andere) benötigt wird, klicken Sie unter Struktur auf die Schaltfläche Bearbeiten und navigieren Sie zum Schema für den Body-Teil. Nähere Informationen dazu finden Sie unter Definieren der Request-Struktur und Definieren der Response-Struktur.
8.Definieren Sie unter Parameter die Parameter des Webservice. Klicken Sie optional auf Von URL importieren, um die Parameter aus einer Beispiel-URL des Webservice zu importieren und die Tabelle "Parameter" automatisch zu befüllen (siehe Importieren von Webservice-Parametern aus einer URL). Nachdem Sie die Parameter aus einer URL importiert haben, können Sie den Inhalt der Tabelle "Parameter" bei Bedarf bearbeiten.
| Anmerkung: | Um benutzerdefinierte Request Header zu definieren, fügen Sie einen Parameter mit dem Stil "Header" hinzu, wobei der Parametername dem Header-Namen und der Parameterwert dem Header-Wert entspricht. Falls der Wert des Request Header aus dem Mapping selbst abgerufen werden soll, setzen Sie den Parametertyp auf "Mapbar". Nähere Informationen dazu finden Sie unter Definieren von Webservice-Parametern. |
9.Wenn vom Webservice eine einfache HTTP-Authentifizierung, eine OAuth 2.0-Autorisierung oder Sicherheitseinstellungen auf Basis eines Zertifikats verlangt werden, klicken Sie unter HTTP-Sicherheitseinstellungen auf die Schaltfläche Bearbeiten und füllen Sie die erforderlichen Felder aus, siehe auch Einstellen der HTTP-Sicherheit.
Nachdem Sie auf OK geklickt haben, wird eine neue Webservice-Komponente zum Mapping-Bereich hinzugefügt. Im unten gezeigten Mapping wird ein Webservice aufgerufen, um mit Hilfe eines GET Request ein Produkt anhand seiner ID abzurufen. In diesem konkreten Beispiel hat die ID im HTTP Request den Konstantenwert "2". Sie könnte aber auch ein Parameter im Mapping sein oder von einer von MapForce unterstützten Komponente bereitgestellt werden. Neben dem Parameter id enthält der Request den Header Accept: text/json. Sie können die Request Header mit Hilfe der "header"-Parameter definieren, wie in Definieren von Webservice-Parametern beschrieben.
Beachten Sie, dass die Webservice-Komponente aus zwei Teilen besteht: Request und Response. Über den Request-Teil können Sie Daten aus dem Mapping für den Webservice bereitstellen, während Sie über den Response-Teil die vom Webservice retournierten Daten aufrufen und auf andere Formate mappen können. Die Struktur des Request und Response hängt von den Parametern sowie der Request- oder Response-Struktur ab, die Sie durch Klick auf die Schaltfläche 
definiert haben. Im obigen Webservice-Aufruf ist die Struktur des Request Body nicht definiert, während die Struktur des Response Body als JSON definiert ist. Dadurch kann das Ergebnis des Webservice auf eine JSON-Datei gemappt werden.
Um den Webservice mit Request-Parametern (falls anwendbar) aufzurufen, ziehen Sie Mapping-Verbindungen zwischen einer beliebigen, von MapForce unterstützten Komponente (z.B. einer XML- oder JSON-Datei) und dem Request-Teil. Auf die gleiche Art können Sie auch vom Webservice stammende Daten auf ein anderes Format mappen, indem Sie Mapping-Verbindungen zwischen dem Response-Teil und einem beliebigen anderen, von MapForce unterstützten Komponententyp ziehen. Wenn Sie ein MapForce-Neuling sind und eine Anleitung zum Ziehen von Mapping-Verbindungen benötigen, schlagen Sie nach unter Arbeiten mit Verbindungen.
Auch die vom Webservice zurückgegebenen Response Header können gemappt werden, wenn es sich um zusätzliche Header handelt (solche, die nicht mit "Content" beginnen). Die Header-Werte stehen in der Webservice-Komponente über ein Datenelement namens "Headers" ( 
), das die zwei Child-Elemente "Name" und "Value" enthält, zur Verfügung. Diese Struktur fungiert als Sequenz und ermöglicht Ihnen, Daten von beliebig vielen vom Webservice zurückgegebenen Headern zu mappen. Um die Daten aus den Response Headern auf ein anderes von MapForce unterstütztes Format zu mappen, verbinden Sie den "Headers"-Struktur-Node mit der Zielsequenz im Mapping. Wenn Sie z.B. die Headers-Sequenz (und ihre untergeordneten Datenelemente) mit einer Zeilen-Sequenz (und deren untergeordneten Datenelementen) einer CSV-Komponente verbinden, würde ein Header einer Zeile in einer CSV-Datei entsprechen.
Der Body 
repräsentiert den Entity Body der HTTP-Nachricht. Daten auf dieser Ebene sind binär kodiert, daher werden für eine direkte Interaktion mit diesen Daten MapForce mime-Funktionen benötigt. Beachten Sie, dass normalerweise keinerlei Interaktion mit dem Body erforderlich ist, wenn vom Webservice strukturierte Daten wie z.B. XML oder JSON erwartet werden. Das Mappen von Daten direkt von oder auf den Body ist nur beim Aufruf von Webservices, die unstrukturierten Inhalt erwarten oder zurückgeben, notwendig.
Standardmäßig parst das Datenelement Body per Konfiguration das Ergebnis, wenn der HTTP-Statuscode zwischen 200 und 299 liegt, d.h. das Mapping gibt für Statuscodes über 299 einen Fehler zurück. Außerdem wird auch dann ein Fehler zurückgegeben, wenn die Response nicht geparst werden kann oder der Webservice aufgrund einer nicht zustande gekommenen Verbindung oder DNS-Auflösungsproblemen nicht aufgerufen werden kann. |
In einigen Fällen soll jedoch auch bei HTTP-Statuscodes, die über 299 liegen, kein Fehler ausgegeben werden. Klicken Sie dazu auf die Schaltfläche neben dem Response Body und ändern Sie den HTTP-Statuscodebereich. Alternativ dazu können Sie auch mehrere Response Body-Datenelemente erstellen. Dies ist nützlich, wenn Sie das Mapping auf Basis von Bedingungen behandeln möchten, je nachdem, welcher HTTP-Statuscode vom Webservice retourniert wird. Klicken Sie dazu mit der rechten Maustaste auf den Body des Response-Teils und wählen Sie im Kontextmenü den Befehl Body-Node hinzufügen vor/nach. So könnten Sie z.B. zwei Body-Datenelemente erstellen:
1.einen Body für alle Statuscodes, die sich innerhalb des Bereichs "erfolgreich" (200 bis 299) befinden. Durch Klick auf die Schaltfläche können Sie den Statuscodebereich konfigurieren. Normalerweise sollte die Body-Struktur bei diesem Szenario auf einen "success" (erfolgreich) Output, wie z.B. eine JSON- oder XML-Datei gemappt werden.
2.einen für alle anderen Statuscodes im Bereich zwischen 300 und 599. Einige Webservices stellen eventuell zusätzliche Informationen über Statuscodes im Body bereit. Um den Grund für den Fehler festzustellen, können Sie daher den "erroneous" Body (fehlerhaft) auf einen anderen Output als den "success" Body mappen (zB. einen String)
Wenn mehrere Body -Datenelemente vorhanden sind, wertet MapForce diese von oben nach unten aus. Um die Priorität zu ändern, klicken Sie mit der rechten Maustaste auf das Body-Datenelement und wählen Sie im Kontextmenü den Befehl Nach oben oder Nach unten. Nähere Informationen zur Behandlung der HTTP Response auf Basis von Bedingungen finden Sie unter Behandlung der HTTP Response auf Basis von Bedingungen.
Mappings, die generische HTTP-Webservice-Aufrufe enthalten, können wie die meisten anderen Mappings ausgeführt werden. Es gibt die folgenden Ausführungsmöglichkeiten:
•Manuell mit MapForce durch Klicken auf das Fenster Ausgabe. In diesem Fall steht das Ergebnis des Mapping-Aufrufs sofort im Fenster Ausgabe zur Verfügung. Wenn das Mapping wie im Beispiel oben mehrere Output-Komponenten hat, klicken Sie vor Ausführung des Mappings auf die Schaltfläche Vorschau 
der gewünschten Komponente.
•Mit MapForce Server über die Befehlszeile oder über API-Aufrufe (https://www.altova.com/de/mapforce/mapforce-server.html). Dazu muss das Mapping zuerst zu einer Mapping-Ausführungsdatei kompiliert werden (siehe Kompilieren von Mappings zu MapForce Server-Ausführungsdateien).
•Als wiederholt ausgeführter Auftrag, bei dem MapForce Server von FlowForce Server ausgeführt wird (https://www.altova.com/de/flowforce.html). Siehe auch Bereitstellen von Mappings auf FlowForce Server.
Schrittweise Beispiele zur Erstellung eines generischen Webservice-Aufrufs finden Sie unter: