OpenAPI
Zur Definition von HTTP APIs wird die OpenAPI-Spezifikation herangezogen. Darin sind die Endpoints, Operationen, Input- und Output-Parameter, Sicherheitsparameter und weitere Details einer API normalerweise im JSON- oder YAML-Format beschrieben. MapForce unterstützt die OpenAPI-Spezifikation 2.0 (vormals bekannt als Swagger RESTful API Documentation-Spezifikation), 3.0 und 3.1.
In der Abbildung unten sehen Sie die OpenAPI-Einstellungen, die Sie konfigurieren können. Nähere Informationen zu den einzelnen Einstellungen finden Sie in den Unterabschnitten weiter unten.
OpenAPI-Einstellungen
Um die Parameter eines Webservice-Aufrufs auszufüllen, müssen Sie eine OpenAPI-Datei angeben, die den Webservice beschreibt: Klicken Sie nebenOpenAPI-Datei auf Durchsuchen und wählen Sie die gewünschte Datei aus. Sobald die OpenAPI-Datei ausgewählt ist, werden die Einstellungen dieses Webservice automatisch ausgefüllt. Gegebenenfalls können Sie eine der Einstellungen ändern. Dies hat keinen Einfluss auf die OpenAPI-Datei.
OpenAPI-Datei | Dies ist der Pfad zur OpenAPI-Spezifikationsdatei, in der der Webservice beschrieben ist.
|
Pfad und Operation | Das Feld Pfad bezieht sich auf den Endpoint Ihrer API (z.B. /users), den MapForce benötigt, um die gewünschte Funktion aufzurufen. Alle Pfade sind relativ zur API-Server-URL (siehe unten).
Operationen beziehen sich auf HTTP-Methoden (z.B. GET, DELETE, POST), mit Hilfe derer verschiedene Aktionen an den Pfaden durchgeführt werden. Wählen Sie zuerst einen Pfad und anschließend eine Operation für diesen Pfad aus (z.B. POST /users, um einen neuen Benutzer hinzuzufügen). Unter Umständen stehen mehrere Pfade zur Verfügung und es können für jeden Pfad eine oder mehrere Operationen definiert werden.
Pfad und Operation können über dieselbe Auswählen-Schaltfläche konfiguriert werden. Wenn Sie auf diese Schaltfläche klicken, erscheint ein Dialogfeld (Abbildung unten) und Sie werden aufgefordert, einen Pfad und eine Operation dafür auszuwählen. In der Abbildung unten wurde die POST-Operation für den Pfad /pets ausgewählt.
|
Server | Das Feld Server bezieht sich auf die Basis-URL einer API (z.B., https://api.example.com), zu der die Endpoint-Pfade relativ sind (z.B. https://api.example.com/users).
|
Standardmäßig werden die ausgewählten Felder Server und Pfad in den Verbindungseinstellungen zur URL verkettet (siehe unten).
Verbindungseinstellungen
URL | Im Textfeld URL wird die Adresse (URL) des aufzurufenden Webservice definiert.
| ||
Dynamische URL (wird durch Mapping bereitgestellt) | Wenn Sie die URL des Webservice über das Mapping bereitstellen möchten, aktivieren Sie das Kontrollkästchen Dynamische URL (wird durch Mapping bereitgestellt). Dadurch wird in der Webservice-Konponente im Mapping ein zusätzlicher Input-Konnektor erstellt, mit dem Sie einen Input verbinden können, der die URL des Webservice bereitstellt.
Bei vollständig oder teilweise dynamischen URLs können Sie die URL flexibel nach Bedarf 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 URL 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.
| ||
Timeout | Der Timeout-Parameter definiert das Intervall, nach dem für den Webservice-Aufruf eine Zeitüberschreitung festgestellt wird, falls vom Server keine Antwort kommt. Wählen Sie Unendlich, falls beim Aufruf unbeschränkt lange auf eine Antwort gewartet werden soll.
|
Anmerkungen zu Parametern in einer URL
Sie haben die Möglichkeit, bestimmte Teile der URL in Parameter zu verwandeln und über das Hauptmapping Werte für diese Parameter bereitzustellen. Beachten Sie bei auf diese Art definierten URLs Folgendes:
•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 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.
•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 Sie die Parameter nur in der Tabelle "Parameter" und stellen Sie sicher, dass diese als Abfrage-Parameter definiert sind.
Parameter
Die im der OPenAPI-Datei definierten Parameter werden im Abschnitt Parameter des Dialogfelds Webservice-Call-Einstellungen(Abbildung unten) angezeigt. Für jeden Parameter muss definiert werden, ob der Parameter mapbar ist oder einen festen Wert hat, doch sollten Sie die anderen Einstellungen der in der OpenAPI definierten Parameter unverändert beibehalten, es sei denn sie sind falsch.
Wenn die OpenAPI-Datei aktualisiert wurde und der Service zusätzliche oder andere Parameter erhalten hat, klicken Sie auf die Schaltfläche Zurücksetzen, um die Parameter zu aktualisieren.
Was das Hinzufügen neuer Parameter betrifft, müssen Sie im Abschnitt Parameter normalerweise nur fehlende, nicht dokumentierte Parameter hinzufügen.
Nähere Informationen zu den im Abschnitt Parameter konfigurierbaren Einstellungen finden Sie unter Parameter.
HTTP-Sicherheitseinstellungen
In den folgenden Szenarien müssen unter Umständen HTTP-Sicherheitseinstellungen konfiguriert werden:
•Der Webservice wird über HTTPS aufgerufen. Dafür ist ein Client-Zertifikat erforderlich.
•Vom Server wird ein falsches Zertifikat verwendet. Sie möchten zulassen, dass der Host-Name zwischen Zertifikat und Request nicht übereinstimmt.
•Für den Webservice ist eine einfache HTTP-Authentifizierung oder eine OAuth 2.0-Autorisierung erforderlich.
Nähere Informationen dazu finden Sie unter HTTP-Sicherheitseinstellungen.
Alle Dateipfade relativ zur MFD-Datei speichern
Wenn diese Option aktiviert ist, speichert MapForce die im Dialogfeld Komponenteneinstellungen angezeigten Dateipfade relativ zum Ordner, in dem sich die MapForce Design (.mfd)-Datei befindet. Siehe auch Relative und absolute Pfade.