Parameter
Wenn Sie einen Webservice mit URL-Parametern aufrufen, so müssen die Parameter im Abschnitt Parameter des Dialogfelds Webservice-Call-Einstellungen definiert werden (Abbildung unten). In diesem Dialogfeld können Sie auch den Webservice Request mit benutzerdefinierten Headern definieren.
Als Alternative zur manuellen Definition können Sie die Parameter des Webservice automatisch ausfüllen (durch Import aus einer vorhandenen URL oder einer WADL-Datei).
Um Parameter zu verwalten, verwenden Sie die Schaltflächen Parameter hinzufügen ( 
) bzw. Parameter löschen ( 
).
Weiter unten finden Sie eine Beschreibung der verfügbaren Einstellungen.
Name | Definiert den Namen eines URL-Parameters. Der Parametername muss eindeutig sein und darf aus alphanumerischen Zeichen, Punkten, Bindestrichen und Unterstrichen bestehen. Im Parameternamen sind keine Leerzeichen gestattet. Abhängig vom Parameterstil können auch andere Zeichen zulässig sein. Wenn der Name ungültig ist, wird die entsprechende Zelle rot markiert.
|
Definiert die Syntax (den Stil) eines 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 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 eine HTTP API 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-Zeichen, -._~!$'()*+,;:@%/?#[] , Leerzeichen. Die folgenden Zeichen sind nicht zulässig: =&.
| |
Typ | Definiert den Datentyp des Parameters (string, integer, date, usw.). Dabei kann es sich um jeden beliebigen XML-Schematyp handeln. Beachten Sie, dass ein Wert, der kein String ist, während eines 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.
|
Mapbar | 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.
|
Fester Wert | 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).
|
Obligatorisch | 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.
|
Wiederholt | 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.
|
Beschreibung | 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.
|
Beispiele
In diesem Unterabschnitt werden einige Beispiele mit verschiedenen Parameterkonfigurationen beschrieben.
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 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 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 zur Laufzeit des Mappings durch den tatsächlichen Wert ersetzt. Bei einem Wert von 1 lautet die URL folglich http://example.org/api/products/1.
Um einen id-Wert in Form einer Konstante anstatt über den Wert aus dem 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 wurden zu diesem Zweck in die Spalte 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.
