Beispiel: Aufrufen eines REST-Webservice
In diesem Beispiel wird gezeigt, wie Sie einen generischen HTTP-Webservice über MapForce aufrufen. Die Beschreibung des in diesem Beispiel aufgerufenen Webservice finden Sie unter https://app.swaggerhub.com/apis/FAA/ASWS/1.1.0. Dieser Webservice gibt den aktuellen Status jedes größeren US-Flughafens als XML- oder JSON-Struktur zurück, wobei er den aus drei Buchstaben bestehenden Flughafencode als Argument erhält (z.B. "SFO", "IAD", "ABE", "DFW", usw). Die Mapping-Datei zu diesem Beispiel finden Sie unter dem folgenden Pfad: <Dokumente>\Altova\MapForce2023\MapForceExamples\AirportStatus.mfd .
Die Response des Webservice ist in diesem Beispiel im JSON-Format und wird auf eine JSON-Datei gemappt. Daher wird das JSON-Schema der Webservice Response-Struktur benötigt. Aus Gründen der Einfachheit wurde das JSON-Schema mit XMLSpy anhand einer vom Webservice-Anbieter bereitgestellten Beispiel-Response generiert. Es steht unter dem folgenden Pfad zur Verfügung: <Dokumente>\Altova\MapForce2023\MapForceExamples\AirportStatus.schema.json.
Für den Request-Teil rufen wir den Webservice mit einem Parameter auf, der im Request den Wert "SFO" bereitstellt. Für den Response-Teil mappen wir die Response-Daten auf eine JSON-Datei. Das Mapping besteht folglich aus drei Hauptkomponenten: dem Webservice-Aufruf, dem Input-Parameter und der JSON-Ausgabedatei.
Schritt 1: Hinzufügen der Webservice-Komponente
1.Stellen Sie sicher, dass die Transformationssprache des Mappings BUILT-IN ist.
2.Klicken Sie im Menü Einfügen auf Webservice-Funktion.
3.Klicken Sie unter Service-Definition auf Manuell.
4.Setzen Sie die Request-Methode auf GET und geben Sie als URL https://soa.smext.faa.gov/asws/api/airport/status/{airportCode} ein. Der Wert innerhalb von geschweiften Klammern ist ein Vorlagenparameter, der zur Laufzeit durch den tatsächlichen Flughafencode ersetzt wird (siehe Hinzufügen eines Webservice-Aufrufs (REST) ).
5.Klicken Sie auf die Schaltfläche Parameter hinzufügen ( 
) und fügen Sie zur Tabelle "Parameter" einen neuen Parameter hinzu. Beachten Sie, dass der Name des Parameters mit dem Parameternamen in geschweiften Klammern in der URL identisch sein muss. Wählen Sie als Stil "Vorlage" und als Typ "String" aus und aktivieren Sie die Optionen "Mapbar" und "Obligatorisch". Das Feld "Beschreibung" ist optional.
6.Fügen Sie einen Header hinzu, um dem Webserver mitzuteilen, dass der Client (d.h. MapForce) JSON-Daten in der Response erwartet. Klicken Sie dazu erneut auf die Schaltfläche Parameter hinzufügen ( ), nennen Sie den Parameter "Accept", wählen Sie als Stil "Header" aus und geben Sie als festen Wert "application/json" ein.
7.Klicken Sie unter Response auf die Schaltfläche Bearbeiten und navigieren Sie zum Schema der Webservice Response. Das Schema befindet sich unter dem folgenden Pfad: <Dokumente>\Altova\MapForce2023\MapForceExamples\AirportStatus.schema.json.
8.Klicken Sie auf OK. Der Webservice steht nun im Mapping-Bereich zur Verfügung.
Schritt 2: Hinzufügen des Input-Parameters
1.Klicken Sie im Menü Einfügen auf Input-Komponente einfügen.
2.Geben Sie als Parameternamen "airportCode" ein und deaktivieren Sie die Option Input ist erforderlich (da die Input-Komponente, wie im nächsten Schritt gezeigt, von einer Konstanten bereitgestellt wird).
3.Fügen Sie (über den Menübefehl Einfügen | Konstante) eine Konstante mit dem Wert "SFO" hinzu und verbinden Sie sie mit dem Parameter-Input.
4.Verbinden Sie den Output des Parameters "airportCode" mit dem Input des Request, wie unten gezeigt.
Zu diesem Zeitpunkt ist der Requst-Teil des Webservice fertig. Zur Mapping-Laufzeit wird der Webservice mit dem von der Konstanten bereitgestellten Wert (in diesem Fall "SFO") aufgerufen.
Schritt 3: Hinzufügen der JSON-Ausgabekomponente
1.Klicken Sie im Menü Einfügen auf JSON-Schema/Datei.
2.Navigieren Sie zu <Dokumente>\Altova\MapForce2023\MapForceExamples\AirportStatus.schema.json und klicken Sie auf Öffnen.
3.Sobald Sie aufgefordert werden, eine JSON-Beispieldatei anzugeben, klicken Sie auf Überspringen (eine JSON-Beispieldatei wird nicht benötigt, da diese generiert wird).
4.Stellen Sie sicher, dass im Menü Verbindung der Menübefehl Idente Sub-Einträge automatisch verbinden ausgewählt ist. Wenn Sie die Option aktivieren, sparen Sie im nächsten Schritt Zeit.
5.Verbinden Sie den Node object des Response Body des Webservice mit dem Node object der JSON-Komponente, wie unten gezeigt. Da die Option Idente Sub-Einträge automatisch verbinden im vorigen Schritt aktiviert wurde, werden alle untergeordneten Nodes automatisch verbunden, sodass Sie die Verbindungen nicht einzeln manuell ziehen müssen.
Schritt 4: Ausführen des Mappings
Sie können den Webservice nun aufrufen. Klicken Sie auf das Fenster Ausgabe um das Mapping auszuführen und eine Vorschau der generierten Ausgabe anzuzeigen. Wenn der Webservice-Aufruf erfolgreich ausgeführt werden konnte, wird im Fenster Ausgabe die zurückgegebene JSON-Struktur angezeigt. Wenn der Aufruf nicht erfolgreich ausgeführt werden konnte, gibt MapForce den entsprechenden Fehler zurück. Wie in der Beschreibung des Webservice angegeben, wird vom Webservice der HTTP-Code 500 zurückgegeben, falls es zu einem Fehler bei der Response kommt. Wenn keine Informationen gefunden wurde, erhalten Sie unter Umständen den HTTP-Code 404.
Wenn Sie MapForce Server installiert haben, können Sie das Mapping auch zu einer Mapping-Ausführungsdatei (*.mfx)-Datei kompilieren und es über die Befehlszeile oder über die MapForce Server API auf dem Server-Rechner, auf dem MapForce Server ausgeführt wird, ausführen (siehe Kompilieren von Mappings zu MapForce Server-Ausführungsdateien ).
Sie haben nun einen generischen HTTP-Webservice-Aufruf erstellt, in dem der Flughafenstatus mit Hilfe einer GET-Methode in Echtzeit abgerufen wird. Nähere Informationen zum Arbeiten mit generischen Webservices finden Sie unter Hinzufügen eines Webservice-Aufrufs (REST).