REST-Webservice-Parameter
Wenn Sie einen Webservice mit URL-Parametern aufrufen müssen, so müssen die Parameter im Dialogfeld Webservice-Call-Einstellungen definiert werden. In diesem Dialogfeld können Sie auch den Webservice Request mit benutzerdefinierten Headern definieren. Sie können die Parameterwerte als mapbar (über das Mapping bereitgestellt) oder festgelegt (im Dialogfeld definiert) konfigurieren.
Um Webservice-Parameter zu definieren, gehen Sie folgendermaßen vor:
1.Doppelklicken Sie im Mapping auf die Titelleiste der Webservice-Komponente, oder klicken Sie mit der rechten Maustaste darauf und wählen Sie den Befehl Eigenschaften. Daraufhin wird das Dialogfeld Webservice-Call-Einstellungen aufgerufen.
2.Klicken Sie unter Service-Definition auf Manuell. Sie können die Parameter entweder manuell oder automatisch (durch Import aus einer vorhandenen URL oder einer WADL-Datei) eingeben. Die importierten Parameter stehen anschließend in der Tabelle Parameter zur Verfügung (siehe Unterabschnitt unten), wo Sie diese gegebenenfalls weiter bearbeiten können.
3.Verwenden Sie dazu die Schaltflächen Parameter hinzufügen ( 
) bzw. Parameter löschen ( 
).
Parameter
Die folgenden Unterabschnitte enthalten einen Überblick über die im Dialogfeld WebService-Call-Einstellungen verfügbaren Parameter.
Definiert den Namen des URL-Parameters. Der Parametername muss eindeutig sein und darf aus alphanumerischen Zeichen, Punkten, Bindestrichen und Unterstrichen bestehen. Im Parameternamen sind keine Leerzeichen gestattet.
|
Definiert die Syntax (den Stil) des URL-Parameters.
•Verwenden Sie den Stil Header, um beim Aufruf des Webservice einen Parameter zum HTTP Header hinzuzufügen. Wenn Sie z.B. einen Parameter Accept mit dem Wert text/xml hinzufügen, ist dies dasselbe, wie wenn Sie den Accept: text/xml Header definieren, welcher den Webserver informiert, dass MapForce eine Response im XML-Format erwartet. Nähere Informationen zu HTTP Headern finden Sie in der Message Header-Spezifikation. •Verwenden Sie für URL-Parameter, die Wert-Schlüssel-Paare im Format ?key=value&key=value definieren (z.B. http://example.org/api/products?sort=asc&category=1&page=1) den Stil Abfrage. Zulässige Zeichen sind: ASCII alphanumerisch, Unicode-Zeichen, -._~ /?:@!$'()*; Leerzeichen. Die folgenden Zeichen sind nicht zulässig: =&#. •Verwenden Sie für in geschweifte Klammern gesetzte URL-Parameter (z.B.: http://example.org/api/products/{id}) den Stil Vorlage. Werte für derartige Parameter werden von MapForce entsprechend den https://tools.ietf.org/html/rfc6570 RFC 6570-Regeln mit Escape-Zeichen versehen. •Verwenden Sie für URL-Parameter, die Schlüssel-Wert-Paare im Format ;key=value;key=value; (z.B., http://example.org/api/products;sort=asc;category=1;page=1;) definieren, den Stil Matrix. Um Boolesche Matrixparameter zu verwenden, wählen Sie als Stil Matrix aus und setzen Sie den Typ auf boolean. •Wählen Sie Body, um eine application/x-www-form-urlencoded Request-Struktur an einen REST-Service zu senden (Die Request-Methode muss POST sein). Nähere Informationen zum Format application/x-www-form-urlencoded finden Sie in der URL-Spezifikation. Zulässige Zeichen sind: ASCII alphanumerisch, Unicode chars, -._~!$'()*+,;:@%/?#[] Leerzeichen. Die folgenden Zeichen sind nicht zulässig: =&.
|
Definiert den Datentyp des Parameters (string, integer, date, usw.). Dabei kann es sich um jeden beliebigen XML-Schematyp handeln. Beachten Sie, dass jeder Wert, der kein String ist, während des Webservice-Aufrufs in einen String konvertiert wird. Es ist sinnvoll, einen Typ zu definieren, wenn MapForce Konvertierungsfehlermeldungen anzeigen soll, falls versucht wird, einen Webservice mit falschen Werten aufzurufen.
|
Aktivieren Sie dieses Kontrollkästchen, wenn Sie Werte aus dem Mapping an diesen Parameter übergeben möchten. Diese Option und die Option Fester Wert schließen einander gegenseitig aus.
|
Definiert den Wert des Parameters. Gilt nur, wenn der Parameter einen konstanten Wert hat. Kann nicht angewendet werden, wenn der Parameter mapbar ist (siehe vorige Option).
|
Aktivieren Sie dieses Kontrollkästchen, wenn der Parameter vom Webservice zwingend verlangt wird. MapForce erzwingt bei Parametern, die obligatorisch und außerdem mapbar sind, Validierungsüberprüfungen: Es wird eine Fehlermeldung angezeigt, wenn der Parameter keinen Wert hat.
|
Definiert, ob der Parameter einen einzigen Wert hat oder mehrere Werte haben kann. Diese Einstellung gilt nur für mapbare Parameter. Mit dieser Option können Sie mehrere Werte im selben Webservice-Aufruf über einen einzigen Parameter übergeben. Wenn Sie dieses Kontrollkästchen aktivieren, können Sie eine Sequenz von Werten mit dem Parameterstruktur-Node im Mapping verbinden. MapForce behandelt die Wertesequenz dann ja nach Parameterstil folgendermaßen:
•Bei Vorlagenparametern werden die Werte durch Kommas getrennt an den Webservice übergeben (z.B: http://example.org/api/products/1,2,3). •Bei Abfrageparametern wird der Parametername für jeden Wert wiederholt (z.B: http://example.org/api/products?color=red&color=green&color=blue). •Wenn als Stil Matrix ausgewählt ist, werden mehrere Werte durch Kommas getrennt (z.B.: http://example.org/api/products;color=red;color=green;color=blue;size=big;size=small;). •Bei Auswahl des Stils Header wird der HTTP Header für jeden Wert wiederholt.
|
Enthält die optionale Beschreibung des Parameters. Wenn der Parameter mapbar ist, wird die hier eingegebene Beschreibung in der Mapping-Komponente als Annotation neben dem Mapping-Datenelement angezeigt.
|
Beispiel 1: Header- und Vorlagenparameter
Mit dem unten gezeigten Webservice wird ein Produkt anhand seines Identifiers (id) mit Hilfe der HTTP GET-Methode abgerufen. In der URL des Webservice steht in den geschweiften Klammern der Parameter id. Beachten Sie, dass der Parameter id in der Tabelle "Parameter" vorhanden ist und den Stil Vorlage hat. Der Parameter ist auch mapbar. Dadurch wird der Parameter im Mapping als Struktur-Node, mit dem Sie den Wert von id verbinden können, angezeigt. id könnte z.B. aus einer Datenbank, einer Datei oder einer Konstante stammen. Dieser Parameter würde während der Mapping-Ausführung zur Laufzeit durch den aktuellen Wert ersetzt. Wenn also der Wert "1" ist, wird die URL http://example.org/api/products/1 verwendet.
Um einen id-Wert in Form einer Konstante anstatt über das Mapping bereitzustellen, deaktivieren Sie die Option "Mapbar" und geben Sie den Wert in die Spalte "Fester Wert" ein.
Die Parameter Accept und Accept-Charset haben den Stil Header. Mit Hilfe dieser Parameter können Sie den Webservice mit benutzerdefinierten Request Headern aufrufen. Es gibt zwei Methoden zur Bereitstellung des Header-Werts:
•Lassen Sie die Option Mapbar aktiviert und stellen Sie den benutzerdefinierten Header-Wert über das Mapping bereit oder
•Deaktivieren Sie die Option Mapbar und geben Sie den Wert direkt in die Spalte "Fester Wert" ein.
Beispiel 2: Matrix-Parameter
Im unten gezeigten Webservice wird eine Liste der Produkte abgerufen, die mit den als Argumente bereitgestellten Farb- und Größenwerten übereinstimmen. Die Stil der Parameter ist "Matrix", d.h. sie sind sowohl als Platzhalter in der URL als auch in der Mapping-Tabelle definiert. Beachten Sie, dass die Parameter mapbar sind und die Option "Wiederholt" aktiviert ist. Dadurch wird ihr Wert aus einer Sequenz von Werten im Mapping (z.B. aus einer Liste von Zeilen in einer Textdatei, einem XML-Node oder einer Datenbankspalte) ausgelesen und zur Laufzeit an den Webservice übertragen. Aus einer URL wie der unten gezeigten würde daher die URL http://example.org/api/products/;color=red;color=blue;size=big;size=small, falls vom Mapping die Farben red und blue und die Größen big und small bereitgestellt werden.
Wenn Ihre URL http://example.org/api/products;color=red,blue;size=big,small lauten soll, gehen Sie folgendermaßen vor:
1.Geben Sie die folgende URL ein: http://example.org/api/products;color={color};size={size}
2.Ändern Sie den Parameterstil in der Tabelle "Parameter" in Matrix.
Wenn Ihre URL http://example.org/api/products?color=red,blue&size=big,small lauten soll, gehen Sie folgendermaßen vor:
1.Geben Sie die folgende URL ein: http://example.org/api/products?color={color}&size={size}
2.Ändern Sie den Parameterstil in der Tabelle "Parameter" in Matrix.
Beispiel 3: Abfrageparameter
Im unten gezeigten Webservice wird ebenfalls eine Liste von Produkten abgerufen, die mit der als Argumente bereitgestellten Farbe und Größe übereinstimmen. Dieses Mal wird der Stil "Abfrage" verwendet. Bei diesem Stil müssen die Parameter nicht als Platzhalter in der URL definiert werden, daher werden sie nur in der Tabelle "Parameter" definiert. Nehmen wir in diesem Beispiel an, dass die Parameterwerte fix sind und nicht über das Mapping bereitgestellt werden dürfen. Die Parameterwerte werden zu diesem Zweck unter "Feste Werte" eingegeben und die Option "Mapbar" ist deaktiviert. Daher wird die URL zur Mapping-Laufzeit zu http://example.org/api/products?color=red&size=big.
