Definieren von Webservice-Parametern

www.altova.com Dieses Kapitel drucken Vorherige Seite Eine Ebene nach oben Nächste Seite

Startseite >  Aufrufen von Webservices > Hinzufügen eines Webservice-Aufrufs (REST) >

Definieren von Webservice-Parametern

Wenn Sie einen Webservice mit URL-Parametern aufrufen müssen, so müssen die Parameter im Dialogfeld "Webservice-Call-Einstellungen" explizit definiert werden. In diesem Dialogfeld können Sie auch den Webservice Request mit benutzerdefinierten Headern definieren.

 

So definieren Sie Webservice-Parameter:

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" geöffnet.

mf_ws_03

2.Wählen Sie unter Service-Definition die Option Manuell. Sie können, wie oben gezeigt, die Parameter entweder manuell eingeben oder sie alternativ dazu aus einer vorhandenen URL oder einer WADL-Datei importieren. Die importierten Parameter stehen anschließend in der Tabelle Parameter zur Verfügung, wo Sie diese gegebenenfalls weiter bearbeiten können.
3.Verwenden Sie dazu die Schaltflächen Parameter hinzufügen ( ic_paramadd ) und Parameter löschen ( ic_paramdel ).

 

 

Die Tabelle Parameter enthält die folgenden Spalten:

Name

Definiert den Namen des URL-Parameters. Der Parametername muss eindeutig sein und darf aus Buchstaben, Ziffern, Punkten (.), Bindestrichen (-) und Unterstrichen (_) bestehen. Im Parameternamen sind keine Leerzeichen gestattet.

Stil

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 unter http://www.iana.org/assignments/message-headers/message-headers.xhtml.

 

Verwenden Sie für URL-Parameter, die Wert-Schlüssel-Paare im Format ?key=value&key=value definieren, den Stil "Abfrage".

 

Beispiel: http://example.org/api/products?sort=asc&category=1&page=1

 

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 (http://tools.ietf.org/html/rfc6570).

 

Verwenden Sie für URL-Parameter, die Schlüssel-Wert-Paare im Format ;key=value;key=value; definieren, den Stil "Matrix".

 

Beispiel: http://example.org/api/products;sort=asc;category=1;page=1;

 

Um Boolesche Matrixparameter zu verwenden, wählen Sie als Stil "Matrix" aus und setzen Sie den Typ auf "boolean" (siehe auch nächste Option).

Typ

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. Dennoch ist es 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 (d.h. 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. Sie können damit mehrere Werte im selben Webservice-Aufruf über einen einzigen Parameter übergeben.

 

Wenn Sie dieses Kontrollkästchen aktivieren, können Sie anstelle eines einzigen Werts eine Sequenz von Werten mit dem Parameterstruktur-Node des Mappings 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.

 

 

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" auch deaktivieren und geben Sie den Wert in die Spalte "Fester Wert" ein.

mf_ws_03

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.

mf_ws_04

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 "Vorlage".

 

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 "Vorlage".

 

 

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.

mf_ws_05


© 2019 Altova GmbH