Hinzufügen eines Webservice-Aufrufs (REST)

www.altova.com Dieses Kapitel drucken Vorherige Seite Eine Ebene nach oben Nächste Seite

Startseite >  Aufrufen von Webservices >

Hinzufügen eines Webservice-Aufrufs (REST)

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 Bodies, 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 kein 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). Gegebenenfalls kann XMLSpy Ihre Instanzdatei auch von XML in JSON und umgekehrt konvertieren.
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. Sie 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 ic-wsdl-func).
2.Klicken Sie unter "Service-Definition" auf Manuell.

mf_ws_01

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.Geben Sie die URL des Webservice ein. Wenn in der URL des Webservice Parameter verwendet werden, beachten Sie Folgendes:
a.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.
b.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".

Ein Beispiel dazu finden Sie unter Definieren von Webservice-Parametern.

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, siehe 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 HTTP-Authentifizierung 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.

mf_ws_02

Für das oben gezeigte Mapping wurden drei Ausgaben definiert:

 

1.der vom Webservice-Aufruf retournierte HTTP-Statuscode
2.die Response Header als kommagetrennte Werte
3.die JSON-Response-Struktur

 

Dies dient nur zu Demozwecken. Sie können ein Mapping auch so entwerfen, dass es nur einen Output hat, z.B. den HTTP-Statuscode. Wenn ein Mapping mehrere Outputs hat, wie das oben gezeigte, können Sie auf die Schaltfläche Vorschau ic-preview-buttondown für die jeweilige Komponente klicken, um vor Ausführung des Mappings eine Vorschau auf diese Ausgabe zu sehen.

 

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 excel1-compicon 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" ( ic_http_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 mf_ic_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 excel1-compicon 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 mf_ic_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 mf_ic_body für alle Statuscodes, die sich innerhalb des Bereichs "erfolgreich" (200 bis 299) befinden. Durch Klick auf die Schaltfläche excel1-compicon 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 Body mf_ic_body 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 Register 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 ic-preview-buttondown 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:

 

Beispiel: Aufrufen eines REST-Webservice
Beispiel: Mappen von Daten von einem RSS Feed

© 2019 Altova GmbH