JSON Post Requests für einen FlowForce Web-Dienst
In diesem Beispiel wird gezeigt, wie Sie einen FlowForce Web-Dienst erstellen, der POST Requests, die im HTTP Request Body JSON-Daten enthalten, verarbeitet. Außerdem wird darin gezeigt, wie Sie den Web-Dienst von einem Client wie MapForce aus aufrufen können.
Der Web-Dienst erhält in diesem Beispiel laut Konfiguration JSON-Daten, Sie könnten aber für einen mit FlowForce Server erstellten Dienst auf ähnliche Weise wie unten gezeigt auch XML-Daten oder andere Inhalte bereitstellen. Der Web-Dienst wurde sehr einfach gehalten. Er erhält nur JSON-Daten und speichert diese ohne weitere Verarbeitung lokal. Der Auftrag kann auch erweitert werden, sodass die JSON-Daten mit RaptorXML Server validiert oder verarbeitet werden, dies ist aber nicht Thema dieses Beispiels.
In diesem Beispiel wird ein Fall gezeigt, in dem die Daten im Body des HTTP Request und nicht als Parameter übermittelt werden. Ein Beispiel, in dem ein Web-Dienst mit Parametern aufgerufen wird, finden Sie unter Bereitstellen eines Auftrags als Web-Dienst.
Voraussetzungen
•Benötigte Lizenzen: FlowForce Server, MapForce Enterprise Edition.
Anmerkungen FlowForce Server bietet eine schnelle Methode, um den Web-Dienst zu erstellen. Die MapForce Enterprise Edition fungiert als Client, der den mit FlowForce Server erstellten Web-Dienst aufruft. Sie können dasselbe Ergebnis auch mit einem anderen Client erzielen. |
•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)
•In diesem Auftrag werden vom Web-Dienst empfangene Input-Daten im lokalen Arbeitsverzeichnis C:\FlowForceExamples\PostJson gespeichert. Dieses Verzeichnis (oder ein ähnliches) muss auf dem Rechner, auf dem FlowForce Server ausgeführt wird, vorhanden sein und ihr Betriebssystembenutzerkonto muss Schreibrechte für dieses Verzeichnis haben.
Erstellen des FlowForce-Auftrags
Melden Sie sich auf der Web-Verwaltungsoberfläche von FlowForce Server an, öffnen Sie den / Container /public/Examples und klicken Sie auf Auftrag erstellen. Geben Sie als nächstes einen Namen und optional eine Beschreibung für den zu erstellenden Web-Dienst ein.
| Anmerkung: | Der Container public/Examples sollte bereits vorhanden sein, wenn Sie das vorherige Beispiel durchgearbeitet haben; erstellen Sie ihn andernfalls mit dem Befehl Erstellen | Container erstellen. |
Damit die POST-Daten im Auftrag als beliebiger Inhalt behandelt werden, muss der Auftrag genau einen Parameter vom Typ Stream haben. Klicken Sie, um den Parameter zu erstellen, auf Parameter hinzufügen 
, geben Sie einen Parameternamen ein (in diesem Beispiel "data") und wählen Sie als Datentyp Stream aus.
Fügen Sie als nächstes einen neuen Ausführungsschritt hinzu und konfigurieren Sie ihn folgendermaßen:
Im oben gezeigten Ausführungsschritt wird die vordefinierte FlowForce-Funktion copy aufgerufen. Der Ausdruck im Textfeld "Quelle" konvertiert den vom Web-Dienst empfangenen Input mit Hilfe der Ausdrucksfunktion as-file in eine Datei (denken Sie daran, dass der Input-Parameter im vorherigen Schritt data genannt wurde). Um diesen Ausdruck automatisch zu erhalten, klicken Sie neben dem Textfeld "Quelle" auf die Schaltfläche 
und wählen Sie data aus.
Das Textfeld "Ziel" enthält einen Ausdruck, der bei jeder Ausführung des Auftrags einen eindeutigen Dateinamen erzeugt. Zu diesem Zweck wird die FlowForce-Ausdrucksfunktion instance-id aufgerufen. Der Name der JSON-Datei sieht also ungefähr folgendermaßen aus "file35.json", wobei bei jeder Auftragsausführung eine andere Nummer generiert wird (Die Nummer entspricht der ID dieser FlowForce-Auftragsinstanz). Sie könnten auch einen vollständigen Dateipfad eingeben, dies ist jedoch nicht notwendig, wenn der "Arbeitsverzeichnis"-Pfad wie in diesem Beispiel definiert wurde. Wenn Sie den Pfad zum Arbeitsverzeichnis definieren, werden alle relativen Dateinamen relativ zum Pfad des Arbeitsverzeichnisses aufgelöst.
Das Verzeichnis C:\FlowForceExamples\PostJSON (oder ein ähnliches, wenn Sie den Pfad geändert haben) muss vorhanden sein und Ihr Betriebssystembenutzer muss Schreibrechte dafür haben. |
Aktivieren Sie unter "Dienst" das Kontrollkästchen Diesen Auftrag über HTTP zur Verfügung stellen und geben Sie für den neuen Web-Dienst "PostJsonService" oder einen ähnlichen Namen ein. Notieren Sie sich den Namen des Diensts; Sie benötigen diesen, um den Webservice aufzurufen.
Wählen Sie unter "Anmeldeinformationen" einen vorhandenen Anmeldeinformationen-Eintrag aus oder definieren Sie lokale Anmeldeinformationen (siehe auch Anmeldeinformationen). Es müssen die Anmeldeinformationen des Benutzerkontos auf dem Betriebssystem, auf dem FlowForce Server ausgeführt wird, sein.
| Anmerkung: | Diese Anmeldeinformationen sind nicht mit denen zu verwechseln, die Sie benötigen, um die FlowForce Server Web-Verwaltungsschnittstelle aufzurufen. |
Klicken Sie auf Speichern. Der Web-Dienst kann nun von einem Client aus aufgerufen werden.
Aufruf des Web-Diensts über einen Browser
Sie können den Web-Dienst auf jede der folgenden Arten über einen Browser aufrufen:
•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/PostJsonService 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 der Auftrag laut Konfiguration einen Stream als Parameter erwartet, werden Sie nun aufgefordert, einen Parameterwert in den Browser einzugeben. Klicken Sie auf Datei auswählen und wählen Sie die JSON-Datei aus, die im POST Request übermittelt werden soll.
Bei Klick auf Submit verarbeitet FlowForce Server den Auftrag und gibt die Response im Browser aus.
Wenn der Auftrag erfolgreich ausgeführt werden konnte, wird im Browser "true" angezeigt und die JSON-Datei wird im Arbeitsverzeichnis C:\FlowForceExamples\PostJson gespeichert. Falls jedoch ein Ausführungsfehler angezeigt wird, finden Sie im Auftrags-Log nähere Informationen dazu, siehe Anzeige des Auftrags-Logs.
Aufrufen des Web-Diensts von MapForce aus
Sie können den Web-Dienst auch von einem anderen Client als dem Webbrowser aus aufrufen, z.B. von der MapForce Enterprise Edition.
1.Klicken Sie im Menü Datei auf Neu, um ein neues Mapping zu erstellen.
2.Klicken Sie im Menü Ausgabe auf Built-In Ausführungsprozessor.
3.Klicken Sie im Menü Einfügen auf Webservice-Funktion. Daraufhin wird das Dialogfeld "Webservice-Call-Einstellungen" aufgerufen.
4.Klicken Sie auf Manuell, wählen Sie als Request-Methode POST aus und geben Sie die URL des Web-Diensts in das Feld "URL" ein. Es handelt sich hierbei um dieselbe URL, mit der Sie den Web-Dienst über den Browser getestet haben.
5.Klicken Sie neben "HTTP-Sicherheitseinstellungen" auf die Schaltfläche Bearbeiten und aktivieren Sie das Kontrollkästchen Dynamische Authentifizierung. Dadurch werden die Anmeldeinformationen während der Ausführung des Mappings interaktiv als Input-Parameter für das Mapping bereitgestellt. Informationen zur Option Anmeldeinformationen verwenden finden Sie unter Anmeldeinformationen in Mapping-Funktionen. Die Eingabe des Benutzernamens und Passworts direkt in dieses Dialogfeld wird nur aus Gründen der Rückwärtskompatibilität unterstützt und wird nicht empfohlen.
6.Klicken Sie auf OK, um das Dialogfeld zu schließen. Das Mapping sieht nun folgendermaßen aus:
7.Fügen Sie mit dem Menübefehl Einfügen | Input-Komponente einfügen drei Input-Parameter zum Mapping hinzu. Die beiden ersten liefern den Benutzernamen bzw. das Passwort. Der dritte liefert die JSON-Daten.
8.Doppelklicken Sie auf jede der obigen Input-Komponenten und geben Sie den Wert ein, der für die Vorschau auf das Mapping zum Zeitpunkt der Designerstellung verwendet werden soll. Geben Sie für die beiden ersten Parameter den Benutzernamen und das Passwort zum Aufrufen des Webservice ein - diese werden benötigt, um das Mapping auszuführen. Aus Sicherheitsgründen wird empfohlen, diese nicht in der Mapping-Datei zu speichern. Geben Sie für den Parameter, der die JSON-Daten bereitstellt, wie unten gezeigt, JSON-Beispieldaten ein, die für die Ausführung dieses Mappings zur Design-Zeit verwendet werden sollen:
| Anmerkung: | Die hier gezeigten JSON-Beispieldaten sind sehr kurz und dienen nur zu Demozwecken. Wenn das Mapping über MapForce Server ausgeführt wird, können Sie die JSON-Daten aus einer tatsächlichen JSON-Datei als Input-Daten für das Mapping bereitstellen. |
9.Fügen Sie mit dem Menübefehl Einfügen | Output-Komponente einfügen die Output-Komponente zum Mapping hinzu.
10.Ziehen Sie die Funktionen charset-encode und mime-entity aus dem Fenster "Bibliotheken" in den Mapping-Bereich und ziehen Sie die Verbindungen, wie unten gezeigt. Außerdem müssen Sie mit dem Menübefehl Einfügen | Konstante zwei Konstanten hinzufügen.
Im obigen Mapping wird der JSON-Input über eine einfache Input-Komponente für das Mapping bereitgestellt. Die Funktionen charset-encode und mime-entity sind vordefinierte MapForce-Funktionen, die den Body des HTTP Request vorbereiten. Der vom Web-Dienst zurückgegebene Statuscode wird auf das vom Mapping zurückgegebene Ergebnis gemappt.
Den Body des HTTP Request, wie oben gezeigt, unstrukturiert vorzubereiten, ist nur eine der Möglichkeiten, um Daten im POST Request zu übermitteln. Bei JSON- und XML-Strukturen können Sie das JSON- oder XML-Schema des Request stattdessen im Dialogfeld "Webservice-Call-Einstellungen" definieren. In diesem Fall werden für den Body der Webservice-Komponente Mapping-Inputs (Konnektoren) auf Basis der JSON/XML-Struktur des Request bereitgestellt. |
Durch Klicken auf das Register Ausgabe können Sie das Mapping nun mit MapForce ausführen. Wenn es zu einem Fehler kommt, wird dieser im Fenster "Meldungen" angezeigt. Um den Fehler zu beheben, müssen Sie eventuell auch das FlowForce Server Log überprüfen (vorausgesetzt der POST Request hat den Server überhaupt erreicht). Falls die Ausführung erfolgreich war, geschieht Folgendes:
1.Im Fenster Ausgabe wird der HTTP-Statuscode "200" angezeigt.
2.Auf der Seite des Servers werden die gesendeten JSON-Daten in eine Datei geschrieben und im Verzeichnis C:\FlowForceExamples\PostJson gespeichert.
In MapForce können Sie genau konfigurieren, was im Mapping geschehen soll, wenn ein Fehler auftritt. Das Mapping kann auch mit MapForce Server ausgeführt oder auf FlowForce Server als Auftrag oder sogar weiterer Webservice bereitgestellt werden. Nähere Informationen dazu finden Sie in der MapForce-Dokumentation https://www.altova.com/de/documentation.