WSDL Lesen für Einsteiger

Thomas Bayer

Von: Thomas Bayer
Datum: 12.09.2009
Letztes Update: 10.01.2012


Ein WSDL Dokument beschreibt die Schnittstelle eines Web Service und dient zur Generierung von Client- oder Service-Code. Werkzeuge, wie z.B. Code Generatoren sind dazu gebaut, WSDL zu verstehen. Für uns Menschen wirkt WSDL unübersichtlich und unverständlich. Im Laufe des Artikels wird aus dem Inhalt eines WSDL Dokumentes ein Baumdiagramm erstellt, welches die Struktur von WSDL illustriert. Der Leser bekommt so ein Verständnis der WSDL Elemente und deren Beziehung zueinander.

Als Beispiel für diesen Artikel dient uns die WSDL eines öffentlichen Services für Bankleitzahlen. Am besten drucken sie sich die WSDL aus oder laden Sie sich diese in einen Text- oder WSDL Editor.

Wir beginnen mit dem Root-Elementdes WSDL Dokumentes, welches den Namen definitions trägt. Die Kindelemente von definitions analysieren wir nicht in der Reihenfolge des Dokumentes, sondern von unten nach oben. Dadurch können wir Verweise in WSDL Dokument besser verfolgen. Definition and Service

Abbildung 1: Definitions und Service

Am Ende der BLZService WSDL finden wir das letzte Kindelement von definitions namens service.

<wsdl:service name="BLZService">
  <wsdl:port name="BLZServiceSOAP11port_http" binding="tns:BLZServiceSOAP11Binding">
    <soap:address location="http://www.thomas-bayer.com:80/axis2/services/BLZService"/>
  </wsdl:port>
  <wsdl:port name="BLZServiceSOAP12port_http" binding="tns:BLZServiceSOAP12Binding">
    <soap12:address location="http://www.thomas-bayer.com:80/axis2/services/BLZService"/>
  </wsdl:port>
  <wsdl:port name="BLZServiceHttpport" binding="tns:BLZServiceHttpBinding">
    <http:address location="http://www.thomas-bayer.com:80/axis2/services/BLZService"/>
  </wsdl:port>
</wsdl:service>
Listing 1: Service Element

Der Name des Services lautet BLZService. Ein Service kann mehrere Ports haben, wie in Abbildung 2 mit einem * dargestellt. Jeder Port beschreibt eine Möglichkeit den Service aufzurufen. In unserem Beispiel gibt es drei Ports. Einen für SOAP 1.1, einen für SOAP 1.2 und einen für das HTTP Binding.

Ports of a Service

Abbildung 2: Ports des BLZService

Sehen wir uns den ersten Port in Listing 2 genauer an.

  <wsdl:port name="BLZServiceSOAP11port_http" binding="tns:BLZServiceSOAP11Binding">
    <soap:address location="http://www.thomas-bayer.com:80/axis2/services/BLZService"/>
  </wsdl:port>
Listing 2: Port für einen SOAP 1.1 Endpoint

Sein Kindelement address hat einen anderen XML Prefix als die anderen Elemente. Der Prefix soap ist an das SOAP 1.1 Binding aus diesem Dokument gebunden. Anstatt des SOAP Bindings können auch andere Bindings für den JMS oder Dateizugriff verwendet werden. Das address Element besitzt ein Attribut namens location, welches auf eine Endpoint Adresse des Service zeigt.

Endpoint Address

Abbildung 3: Endpoint Adresse

Als nächstes interessiert und das binding Attribut des Ports. Der Wert tns:BLZServiceSOAP11Binding zeigt auf ein Binding, das ein wenig höher im Dokument steht. In diesem Beispiel zeigt jeder Port auf ein anderes Binding. Deswegen hat die BLZService WSDL drei Bindings.

A Port references a Binding

Abbildung 4: Referenz von Port auf Binding

Ein Binding liefert Details über den spezifischen Transportweg. Das Binding in Abbildung 5 besitzt zwei verschiedene Arten von Kindelementen.

SOAP Binding

Abbildung 5: SOAP Binding

Als erstes werfen wir einen einen Blick auf das soap:binding Element in Listing 3. Der Wert des transport Attributes ist eine URI, die bestimmt, dass SOAP Nachrichten über HTTP übertragen werden sollen. Der Wert document des style Attributs gibt uns zusammen mit dem use Attribut aus den soap:body Elementen einen Hinweis über den Nachrichtenstil. In unserem Beispiel benutzen wir ein Document/Literal Nachrichtenstil.
Ein Binding kann verschiedene Transport Optionen für jede einzelne Methode des Services spezifizieren.

  <wsdl:binding name="BLZServiceSOAP11Binding" type="tns:BLZServicePortType">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
    <wsdl:operation name="getBank">
      <soap:operation soapAction="" style="document"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
Listing 3: SOAP 1.1 Binding

Schauen Sie sich nun Listing 4 an. Sie finden dort die Transport Optionen der getBank Methode. In dem wsdl:operation Element befindet sich in Zeile 2 ein soap:operation Element, welches Einzelheiten zum SOAP Protokoll und dessen Transport festlegt. Die soapAction ist ein Überbleibsel von früher. Das Basic Profile der Web Services Interoperability Organization sieht vor, dass soapAction mit einem leeren String belegt werden sollte.

  <wsdl:operation name="getBank">
      <soap:operation soapAction="" style="document"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
Listing 4: Binding Operation

Da bei Web Services der Focus auf Nachrichten und nicht auf Parametern liegt, können die Informationen über den Transport dieser Nachrichten in den wsdl:input und wsdl:output Elementen gefunden werden. Ein Service kann auch einen oder mehrere Faults als Output spezifizieren.

Binding Operation

Abbildung 6: Binding Operation

Das soap:body und das soap:header Element können weitere Besonderheiten einer Nachricht beschreiben. Im Beispiel wird für den Nachrichtenstil immer literal verwendet.

soap:body Elements

Abbildung 7: soap:body Elemente

Lassen Sie uns im WSDL weiter nach oben gehen. Verfolgen wir nun den Wert des type Attributes des Bindings. Es zeigt auf einen portType gleichen Namens weiter oben im Dokument.

Binding referencing a PortType

Abbildung 8: Das Binding referenziert einen PortType

Wir haben jetzt die Grenze zwischen den konkreten Details des Transportes sowie der Location eines Services und der abstrakten Beschreibung des Interfaces überschritten. PortType ist in WSDL 1.1 dasselbe wie das Interface eines Web Services. In WSDL 2.0 assoziiert der Ausdruck portType das Interface des Services. Ein Interface kann mehrere Operationen besitzen. Eine Operation entspricht einer Funktion in der prozeduralen Programmierung. Die WSDL des BLZService hat nur einen portType. Alle drei Bindings referenzieren den portType namens BLZServicePortType.

Operations of a portType

Abbildung 9: Operationen eines portType

In einem portType finden wir wie im Binding operation Elemente. Diesmal beschreiben input und output allerdings die Struktur der Nachricht und nicht transportspezifische Optionen.

Input and Output of an Operation

Abbildung 10: Input und Output einer Operation

Das message Attribut des Inputs referenziert wieder einen Teil weiter oben im WSDL Dokumentes. Und zwar eine Nachricht namens tns:getBank. Weiter oberhalb finden wir die dazugehörige Nachricht mit diesem Namen.

  <wsdl:portType name="BLZServicePortType">
    <wsdl:operation name="getBank">
      <wsdl:input message="tns:getBank"/>
      <wsdl:output message="tns:getBankResponse" wsaw:Action="http://thomas-bayer.com/blz/BLZService/getBankResponse"/>
    </wsdl:operation>
  </wsdl:portType>
Listing 5: Interface Beschreibung des Service
Message

Abbildung 11: Message

Die Nachricht getBank hat ein part Element als Kind. Ein WSDL Experte wird anhand des Attributes name und dessen Wert parameters erkennen, dass es sich um den Substyle Wrapped des Document/Literal Stils handelt.

  <wsdl:message name="getBank">
    <wsdl:part name="parameters" element="tns:getBank"/>
  </wsdl:message>
Listing 6: getBank Nachricht

Das Attribut element in Zeile 2 zeigt wieder weiter nach oben. Es referenziert auf das tns:getBank Element, welches im XML Schema zu finden ist.

A Message and its parts

Abbildung 12: Eine Nachricht und deren parts

Das nächste Kind von definitions lautet types.

The Types Section

Abbildung 13: Die types Sektion

Das types Element kann mehrere XML Schemas als Kinder besitzen.

Schemas used in a WSDL

Abbildung 14: Die in der WSDL benutzten Schemas

Listing 7 zeigt das types Element und ein eingebettetes Schema.

  <wsdl:types>
    <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://thomas-bayer.com/blz/">
      <xsd:element name="getBank" type="tns:getBankType"/>
      <xsd:element name="getBankResponse" type="tns:getBankResponseType"/>
      <xsd:complexType name="getBankType">
        <xsd:sequence>
          <xsd:element name="blz" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
      <xsd:complexType name="getBankResponseType">
        <xsd:sequence>
          <xsd:element name="details" type="tns:detailsType"/>
        </xsd:sequence>
      </xsd:complexType>
      <xsd:complexType name="detailsType">
        <xsd:sequence>
          <xsd:element minOccurs="0" name="bezeichnung" type="xsd:string"/>
          <xsd:element minOccurs="0" name="bic" type="xsd:string"/>
          <xsd:element minOccurs="0" name="ort" type="xsd:string"/>
          <xsd:element minOccurs="0" name="plz" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>
  </wsdl:types>
Listing 7: Eingebettetes XML Schema

In einem Schema findet man die Definition von:

  • Komplexen Typen
  • Simplen Typen

sowie die Deklaration von:

  • Elementen
Das XML Schema im BLZService ist ein typisches Schema für Web Services, welches nur complexTypes und elements als Toplevel Schema Komponenten besitzt.

A part can reference an Element

Abbildung 15: Ein part kann ein element referenzieren

Listing 8 stellt die Deklaration des getBank Elements dar.

  <xsd:element name="getBank" type="tns:getBankType"/>
Listing 8: Deklaration von getBank

Dieses Element ist vom Typ complexType und heisst getBankType und wird woanders im Schema definiert.

An Element references its Type

Abbildung 16: Das element referenziert einen type

Der Typ dieses Elements hat eine sequence als Modelgroup, die ein Element namens blz des build-in Schema Types string besitzt.

A ComplexType with a Sequence as Content

Abbildung 17: Ein complexType mit einer sequence

Listing 9 zeigt die Definition des getBankType.

  <xsd:complexType name="getBankType">
        <xsd:sequence>
          <xsd:element name="blz" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
Listing 9: The ComplexType getBankType

Eine sequence kann aus mehreren Elementen bestehen, die die Reihenfolge der Elemente in einer SOAP Nachricht beschreiben.

The entire Structure of a WSDL Document

Abbildung 18: Die komplette Struktur eines WSDL Dokuments

Nun haben wir uns die gesamte WSDL Beschreibung des Beispielservices angeschaut.

Alle WSDL Dokumente haben dieselbe Struktur wie der BLZService. Um eine WSDL zu verstehen, beginnt man mit dem Lesen am Ende des Dokuments und arbeitet sich nach oben vor, indem man den Verweisen in den Attributen folgt.

Ich hoffe, dass der Artikel Ihnen den Einstieg in WSDL erleichtert hat.

Thomas Bayer
bayer@predic8.com

References

Share

WSDL Versionen vergleichen

Im Artikel erfahren Sie, wie unterschiedliche Versionen eines WSDL Dokumentes automatisch verglichen werden können.

WSDL Analyzer

Erzeugen Sie Reports zur Qualitätssicherung aus Ihrer WSDL.

Service Design

Wir unterstützen Sie bei der WSDL Erstellung und Qualitätssicherung. Besuchen Sie die Service Design Schulung oder planen Sie einen Workshop.

WSDL Parser

Lesen, vergleichen und erzeugen Sie WSDL Dokumente mit dem freien SOA Model einer Java API für WSDL und XML Schema.

Web Services Kurse

Lernen Sie SOAP und WSDL in der CXF Schulung oder im JAX-WS Seminar.