Powered by SmartDoc
<< Webサービスの基礎(2004年度ソフトウェア特論)/ WSDL

WSDL

WSDLとは何か

WSDLとは、Webサービスの具体的な内容を書いてある文書です。Webサービスを利用するためにはどこにアクセスすればよいのか、またどのようなメソッドが使えるのかなどの情報が記述されています。Java言語でのインタフェースのようなものです。SOAPと同じくWSDLもXMLで記述されています。

Google Web APIsでも、このWebサービスの内容を示すWSDL文書が付属しています。

WSDLから、Webサービスにアクセスするクライアントプログラムを生成できます。例えばJavaのWebサービス開発キットであるJWSDPでは、wscompileというツールでWSDLからJavaプログラムを生成します。クライアントプログラムからはメソッドを呼び出すだけであり、具体的な処理内容はWebサービス側にあるので、これでうまくいくのです。

また、既存のプログラムからWSDLを生成することもできます。

WSDLはWeb Services Description Languageの略で、日本語では「Webサービス記述言語」と訳されます。

WSDLの構造

WSDLの例

ではWSDLの例として、Google Web APIsで提供されているWSDLであるGoogleSearch.wsdlについて見てみましょう。

GoogleSearch.wsdl
<?xml version="1.0"?>

<!-- WSDL description of the Google Web APIs.
     The Google Web APIs are in beta release. All interfaces are subject to
     change as we refine and extend our APIs. Please see the terms of use
     for more information. -->

<!-- Revision 2002-08-16 -->

<definitions name="GoogleSearch"
             targetNamespace="urn:GoogleSearch"
             xmlns:typens="urn:GoogleSearch"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
             xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
             xmlns="http://schemas.xmlsoap.org/wsdl/">

  <!-- Types for search - result elements, directory categories -->

  <types>
    <xsd:schema xmlns="http://www.w3.org/2001/XMLSchema" 
                targetNamespace="urn:GoogleSearch">
            
      <xsd:complexType name="GoogleSearchResult">
        <xsd:all>
<xsd:element name="documentFiltering" type="xsd:boolean"/>
<xsd:element name="searchComments" type="xsd:string"/>
          <xsd:element name="estimatedTotalResultsCount"  type="xsd:int"/>
<xsd:element name="estimateIsExact" type="xsd:boolean"/>
<xsd:element name="resultElements" type="typens:ResultElementArray"/>
<xsd:element name="searchQuery" type="xsd:string"/>
          <xsd:element name="startIndex"                  type="xsd:int"/>
          <xsd:element name="endIndex"                    type="xsd:int"/>
<xsd:element name="searchTips" type="xsd:string"/>
<xsd:element name="directoryCategories" \
    type="typens:DirectoryCategoryArray"/>
<xsd:element name="searchTime" type="xsd:double"/>
        </xsd:all>
      </xsd:complexType>

      <xsd:complexType name="ResultElement">
        <xsd:all>
          <xsd:element name="summary" type="xsd:string"/>
          <xsd:element name="URL" type="xsd:string"/>
          <xsd:element name="snippet" type="xsd:string"/>
          <xsd:element name="title" type="xsd:string"/>
          <xsd:element name="cachedSize" type="xsd:string"/>
<xsd:element name="relatedInformationPresent" type="xsd:boolean"/>
          <xsd:element name="hostName" type="xsd:string"/>
<xsd:element name="directoryCategory" type="typens:DirectoryCategory"/>
          <xsd:element name="directoryTitle" type="xsd:string"/>
        </xsd:all>
      </xsd:complexType>
  
      <xsd:complexType name="ResultElementArray">
        <xsd:complexContent>
          <xsd:restriction base="soapenc:Array">
<xsd:attribute ref="soapenc:arrayType" \
    wsdl:arrayType="typens:ResultElement[]"/>
          </xsd:restriction>
        </xsd:complexContent>
      </xsd:complexType>

      <xsd:complexType name="DirectoryCategoryArray">
        <xsd:complexContent>
          <xsd:restriction base="soapenc:Array">
<xsd:attribute ref="soapenc:arrayType" \
    wsdl:arrayType="typens:DirectoryCategory[]"/>
          </xsd:restriction>
        </xsd:complexContent>
      </xsd:complexType>

      <xsd:complexType name="DirectoryCategory">
        <xsd:all>
          <xsd:element name="fullViewableName" type="xsd:string"/>
          <xsd:element name="specialEncoding" type="xsd:string"/>
        </xsd:all>
      </xsd:complexType>

    </xsd:schema>
  </types> 

  <!-- Messages for Google Web APIs - cached page, search, spelling. -->
             
  <message name="doGetCachedPage">
    <part name="key"            type="xsd:string"/>
    <part name="url"            type="xsd:string"/>
  </message>

  <message name="doGetCachedPageResponse">
    <part name="return"         type="xsd:base64Binary"/>
  </message>

  <message name="doSpellingSuggestion">
    <part name="key"            type="xsd:string"/>
    <part name="phrase"         type="xsd:string"/>
  </message>

  <message name="doSpellingSuggestionResponse">
    <part name="return"         type="xsd:string"/>
  </message>

  <!-- note, ie and oe are ignored by server; all traffic is UTF-8. -->

  <message name="doGoogleSearch">
    <part name="key"            type="xsd:string"/>
    <part name="q"              type="xsd:string"/>
    <part name="start"          type="xsd:int"/>
    <part name="maxResults"     type="xsd:int"/>
    <part name="filter"         type="xsd:boolean"/>
    <part name="restrict"       type="xsd:string"/>
    <part name="safeSearch"     type="xsd:boolean"/>
    <part name="lr"             type="xsd:string"/>
    <part name="ie"             type="xsd:string"/>
    <part name="oe"             type="xsd:string"/>
  </message>

  <message name="doGoogleSearchResponse">
<part name="return" type="typens:GoogleSearchResult"/>
  </message>

  <!-- Port for Google Web APIs, "GoogleSearch" -->

  <portType name="GoogleSearchPort">

    <operation name="doGetCachedPage">
      <input message="typens:doGetCachedPage"/>
      <output message="typens:doGetCachedPageResponse"/>
    </operation>

    <operation name="doSpellingSuggestion">
      <input message="typens:doSpellingSuggestion"/>
      <output message="typens:doSpellingSuggestionResponse"/>
    </operation>

    <operation name="doGoogleSearch">
      <input message="typens:doGoogleSearch"/>
      <output message="typens:doGoogleSearchResponse"/>
    </operation>

  </portType>


  <!-- Binding for Google Web APIs - RPC, SOAP over HTTP -->

  <binding name="GoogleSearchBinding" type="typens:GoogleSearchPort">
    <soap:binding style="rpc"
                  transport="http://schemas.xmlsoap.org/soap/http"/>

    <operation name="doGetCachedPage">
      <soap:operation soapAction="urn:GoogleSearchAction"/>
      <input>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </input>
      <output>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </output>
    </operation>

    <operation name="doSpellingSuggestion">
      <soap:operation soapAction="urn:GoogleSearchAction"/>
      <input>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </input>
      <output>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </output>
    </operation>

    <operation name="doGoogleSearch">
      <soap:operation soapAction="urn:GoogleSearchAction"/>
      <input>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </input>
      <output>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </output>
    </operation>
  </binding>

  <!-- Endpoint for Google Web APIs -->
  <service name="GoogleSearchService">
    <port name="GoogleSearchPort" binding="typens:GoogleSearchBinding">
      <soap:address location="http://api.google.com/search/beta2"/>
    </port>
  </service>

</definitions>

全体的な構造

WSDLの全体的な構造は、次のようになります。

<definitions>
        <types>     ……    </types>
        <message>   ……    </message>
        <portType>  ……    </portType>
        <binding>   ……    </binding>
        <service>   ……    </service>
</definitions>

WSDLの内容を細かく読むときには、service要素からtypes要素に向かって、下から順に読むとわかりやすくなります。

では、service要素から順に見ていきましょう。

service要素

<service name="GoogleSearchService">
    <port name="GoogleSearchPort" binding="typens:GoogleSearchBinding">
        <soap:address location="http://api.google.com/search/beta2"/>
    </port>
</service>

service要素のname属性によって、GoogleSearchServiceというサービス名が付けられています。

service要素では、主にエンドポイントを指定します。エンドポイントとは、Webサービスを提供しているURLのことです。エンドポイントは、soap:address要素のlocation属性で指定します。

<soap:address location="http://api.google.com/search/beta2"/>

このWebサービスは、"http://api.google.com/search/beta2"というURLにアクセスするということになります。

次に、port要素のbinding属性を見てみましょう。ここの値は、"typens:GoogleSearchBinding"となっています。この値は、次に紹介するbinding要素のname属性の値です。

<port name="GoogleSearchPort" binding="typens:GoogleSearchBinding">
        ……
</port>

binding要素

binding要素について見てみましょう。

  <binding name="GoogleSearchBinding" type="typens:GoogleSearchPort">
    <soap:binding style="rpc"
                  transport="http://schemas.xmlsoap.org/soap/http"/>

    ......

    <operation name="doGoogleSearch">
      <soap:operation soapAction="urn:GoogleSearchAction"/>
      <input>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </input>
      <output>
        <soap:body use="encoded"
                   namespace="urn:GoogleSearch"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      </output>
    </operation>
  </binding>

まず、binding要素のname属性によって、GoogleSearchBindingというバインディング名が付けられています。

そして、type属性を見てみましょう。この値は、次に紹介するportType要素のname属性の値です。

<binding name="GoogleSearchBinding" type="typens:GoogleSearchPort">
    ……
</binding>

次に、binding要素の子要素であるsoap:binding要素です。

style属性では通信の方法を指定します。ここでは"rpc"が指定されています。ほかには、"document"が入ることもあります。

transport属性では、Webサービスを動かすためにトランスポート層でどのようなプロトコルを使うか指定します。ここでは、HTTPプロトコルが指定されています。

    <soap:binding style="rpc"
          transport="http://schemas.xmlsoap.org/soap/http"/>

operation要素です。

operation要素は、このWebサービスで利用できる操作について定義します。Javaではメソッドに対応します。

子要素であるinput要素はメソッドの引数に、output要素はメソッドの返値にそれぞれ対応します。

<operation name="doGoogleSearch">
    <input>   ......      </input>
    <output>  ......      </output>
</operation>

input要素の中を見ると、このような記述になっています。output要素の中も同様です。ここでは、input (引数)とoutput (返値)のいずれも、SOAPでデータが渡されるときに「SOAPエンコーディング」という手法が使われることを示しています。ただし、この「SOAPエンコーディング」は、現在ではあまり推奨されない手法となっています。

<operation name="doGoogleSearch">
  <input>
    <soap:body use="encoded"
        namespace="urn:GoogleSearch"
        encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  </input>
  ......

binding要素での処理についてまとめると、主にWebサービスの通信の方法について定めています。例えば、トランスポート層としてHTTPを使う、SOAPを利用する、SOAPエンコーディングを利用する、といった点です。

portType要素

portType要素です。

<portType name="GoogleSearchPort">
  ......
  <operation name="doGoogleSearch">
    <input message="typens:doGoogleSearch"/>
    <output message="typens:doGoogleSearchResponse"/>
  </operation>
</portType>

まず、portType要素のname属性によって、GoogleSearchPortというポート名が付けられています。

portType要素の子要素には、binding要素で出てきたoperation要素があります。operation要素のinput, output要素では、引数や返値の型を指定します。ここでは抽象的な名前だけを指定し、型の具体的な内容はmessage要素で指定します。

  <operation name="doGoogleSearch">
    <input message="typens:doGoogleSearch"/>
    <output message="typens:doGoogleSearchResponse"/>
  </operation>

input要素では、doGoogleSearchが指定されています。このdoGoogleSearchはi、message要素で定められています。また、output要素では、doGoogleSearchResponseが指定されています。

まとめると、portType要素は、メソッドの名前、引数や返値の型など、Javaのインタフェースに相当する機能を持っています。

message要素

message要素です。

<message name="doGoogleSearch">
  <part name="key"	 type="xsd:string"/>
  <part name="q"	     type="xsd:string"/>
  <part name="start"	 type="xsd:int"/>
  ......
</message>

<message name="doGoogleSearchResponse">
  <part name="return"
           type="typens:GoogleSearchResult"/>           
</message>

message要素は、portType要素のinput・output要素で使われる型を指定します。

このWSDLでは、“doGoogleSearch”というmessageには

などが含まれます。

こうしたkey, q, startといったものは、portType要素の中で定義されているdoGoogleSearchオペレーションの引数に対応するのです。

part要素での型の指定では、xsd:string, xsd:intなどのXML Schema組み込みの型を利用します。

<message name="doGoogleSearch">
  <part name="key"	 type="xsd:string"/>
  <part name="q"	     type="xsd:string"/>
  <part name="start"	 type="xsd:int"/>
  ......
</message>

組み込みのデータ型で対応できないときは、後述するtypes要素で新しい型を作成します。ここでは、GoogleSearchResultという新しい型をtypes要素で指定しています。

<message name="doGoogleSearchResponse">
  <part name="return"
           type="typens:GoogleSearchResult"/>           
</message>

types要素

最後に、types要素です。

<types>
    <xsd:schema xmlns=
       "http://www.w3.org/2001/XMLSchema" 
       targetNamespace="urn:GoogleSearch">
    <xsd:complexType name="GoogleSearchResult">
       <xsd:all>
         <xsd:element name="documentFiltering" 
                      type="xsd:boolean"/>
         <xsd:element name="resultElements"              
                      type="typens:ResultElementArray"/>
         ......
       </xsd:all>
         ......
    </xsd:complexType>
         ......
</types>

XML Schemaを使って、GoogleSearchResultという新しい型を生成します。

また、それぞれの要素の型を、さらにXML Schemaで宣言することもできます。例えば次の部分では、ResultElementArrayがこのtypes要素中で定義されています。

         <xsd:element name="resultElements"              
                      type="typens:ResultElementArray"/>

WSDLの各要素の概要

WSDLの各要素の役割についてまとめると、次のようになります。

<< Webサービスの基礎(2004年度ソフトウェア特論)/ WSDL