SOAPを利用したWeb API

2006年10月3日 16:06

SOAPの仕組み

   続いてはSOAPを利用したWeb APIについて見ていくことにしましょう。SOAPはSimple Object Access Protocolの略で、XML-RPCと同じようにネットワーク越しにサービスを呼び出すためのデータのやり取りを決めた仕様です。ただしSOAPはXML-RPCと違って、やり取りはHTTPだけでなく、ほかのプロトコルも使うことができるようになっています。

   SOAPの仕様の策定には、XML-RPCを作ったたDave Winer氏も関わっており、シンプルなXML-RPCに、より多くの拡張性を持たせたものだということもできます。

   SOAPでは、XML-RPCと同様にHTTPのPOSTメソッドを利用してXMLデータのやり取りを行います。ただしやり取りされるXMLデータは、XML-RPCよりもやや複雑です。

   まずはサンプルを見てみましょう（リスト12）。

リスト12：SOAPのリクエストメッセージ

<?xml version='1.0' encoding='UTF-8'?>
<env:Envelope
   xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/1999/XMLSchema">
  <env:Header>
    <t:transaction
       xmlns:t="http://api.example.org/transaction"
       env:encodingStyle="http://example.com/encoding"
       env:mustUnderstand="true">5</t:transaction>
  <env:/Header>
  <env:Body>
    <m:exampleMethod
       xmlns:m="http://api.example.org/"
       env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <name xsi:type="xsd:string">Taro Yamada</name>
      <id xsi:type="xsd:int">3232</id>
    </m:exampleMethod>
  </env:Body>
</env:Envelope>

   SOAPのデータのルート要素はEnvelopeです。envelopeは「封筒」という意味で、メッセージ全体をくるむ封筒の役割をする、という意味がこめられています。

   そしてSOAPのデータ全体は、ヘッダー（Header）とボディ（Body）に分かれています。これはちょうどHTTPのヘッダーとボディとよく似ていて、実際に送信するデータをボディに、そしてセッションの保持などの送受信に関する情報や付加情報などをヘッダーに入れることになっています。ただし、ヘッダーは省略可能で、ヘッダーをまったく付けなくても、SOAPの仕様的には正しいものです。

   Body要素の中には、呼び出すメソッド名とパラメータの情報が入ります。記述方法は比較的シンプルで、メソッド名の要素の中にパラメータ名の要素が列挙され、そこにパラメータが入る、というものです。上記のサンプルの場合は呼び出すメソッド名は「exampleMethod」であり、中のパラメータは「name」と「id」ということになります。

   それに対するレスポンスは前ページのリスト13のようなデータになります。

リスト13：SOAPのレスポンスメッセージ

<?xml version='1.0' encoding='UTF-8'?>
<env:Envelope
      xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/1999/XMLSchema">
  <env:Header>
    <t:transaction
           xmlns:t="http://api.example.org/transaction"
           env:encodingStyle="http://example.com/encoding"
           env:mustUnderstand="true">5</t:transaction>
  <env:/Header>
  <env:Body>
    <m:exampleMethodResponse
         xmlns:m="http://api.example.org/"
         env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <count xsi:type="xsd:int">132</count>
    </m:exampleMethodResponse>
  </env:Body>
</env:Envelope>

   Envelopeによって全体が包まれていて、HeaderとBodyがあるところまではリクエストデータと同じです。Bodyの中の要素名は「メソッド名＋Response」になります。

   そしてその中には、戻り値がやはりパラメータ名を要素名として記述されています。戻り値は1つに限られてはいません。

   ちなみに、SOAPはW3Cによって標準化が行われており、現在の最新版は1.2です。詳しい仕様については以下のページを参照してください。

http://www.w3.org/TR/soap12-part0/

   なお、ここで紹介したサンプルはHTTPのPOSTメソッドを利用していますが、アクセスの結果サーバー側のデータに影響を与えないものであれば、GETメソッドを利用してのアクセスも可能であると定義されています。

   SOAPと同時によく利用される仕組みに「WSDL」があります。これはWeb Services Description Languageの略で、Webサービス、つまりはWeb APIの仕様を記述するためのデータ形式です。WSDL自体はXMLで記述されており、ある公開されているWeb APIがどんなメソッドを公開しているのか、アクセスすべきURIはどこか、渡すべきパラメータは何か、戻り値は何か、利用すべき名前空間は何か、といったことが記述されています。したがって、WSDLを読み込むことで、プログラムはそのAPIの利用方法を自動的に知ることができるようになります。つまり、リクエストデータを自分で生成しなくても、どのメソッドを呼び出して、どのパラメータに何を渡すかを指定すれば、自動的にリクエストデータを生成してAPIを利用できるようになります。

   WSDLのサンプルをリスト14に示します。これはGoogleが公開している検索APIのWSDLを抜粋したものです。

リスト14：WDSLのサンプル

<?xml version="1.0"?>
<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>
    <xsd:schema xmlns="http://www.w3.org/2001/XMLSchema"
                targetNamespace="urn:GoogleSearch">