Google Apps Script Documentation - Soap Service - Tutorial: Accessing a Soap Service

Googleを追いかけろ！

home >> Soap Services >> Tutorial: Accessing a Soap Service

■ Soapサービスの呼び出し方法をガイドします。
index;
* Section 1: Creating a Wsdl Object
* Section 2: Querying a Wsdl Object
* Section 3: Getting a WsdlService Object
* Section 4: Querying a WsdlService Object
* Section 5: Creating Web Service Paramaters
* Section 6: Testing a Soap Operation
* Section 7: Invoking a Soap Operation
* Section 8: Working with a Soap Operation Result
* Summary and Complete Code
■ 参考：Class SoapService, Class Wsdl, Class WsdlService, Class SoapOperation

* Section 1: Creating a Wsdl Object

このデモンストレーションのために”WebserviceX called GeoIPService”から提供されているフリーで簡単に利用できるSOAPサービスを利用します。このウェブサービスは指定した”IP Address”の国別検索を可能にするサービスです。
SOAP libraryを使用するためには先ずウェブサービスに関連付けられたWSDLファイルが必要です。 'Web Service Definition Language'を意味するWSDLファイルには、SOAP libraryがサービスの所在と利用可能なサービスを取得できるためのメタデータが必須になります。
このチュートリアルで使用するWSDLは”http://www.webservicex.net/geoipservice.asmx?wsdl”にあります。本当にちょっとしたXMLファイルです。ここにはどのようなサービスや操作が利用可能なのか説明されています。また、そのために必要な指定すべき引数のタイプなども書かれています。
さて、WSDLファイルの所在が分かったので、Google Web Scriptsを利用して始めてみます。

var wsdl = SoapService.wsdl("http://www.webservicex.net/geoipservice.asmx?wsdl");

* Section 2: Querying a Wsdl Object

”SoapService.wsdl”は幾つかの役立ちそうなメソッドを持つWsdlオブジェクトのタイプを返します。これを特定のロケーションにおけるWSDL記述の内容を知るのに利用します。ここで、”getServiceNames”関数を使って利用可能なサービス決定します。通常はシングルサービスで利用可能ですが、時には増えても大丈夫です。このメソッドの呼び出しとそのログ取得は下のようにします。

 Logger.log(wsdl.getServiceNames());

戻り値が取得できたらログをチェックします。'GeoIPService'の名前が見つかるでしょう。これは下のようにオリジナルのWSDLファイルの中でもひとつのサービスとして定義されてます。

  <wsdl:service name="GeoIPService">

* Section 3: Getting a WsdlService Object

さっそくどのような操作を可能にするサービスなのかを見てみます。実行可能なサービスには２つのメソッドがあります。ひとつ目はサービス名を使ってWsdlオブジェクト上の”getService”を呼び出すだけです。

 var geoService = wsdl.getService("GeoIPService");

下が２つ目です。

 var geoService = wsdl.getGeoIPService();

さて、このオブジェクトは特定のウェブサービスに対してどのような固有のメソッドを持っているのでしょうか？ javascriptのダイナミックシステムのお陰で、ソープライブラリーは便利なメソッドを生成することができます。そのため、いつでも文字列を渡すことなく目的の挙動をするコードが作成できるのです。最初のフォームを使う理由は何でしょうか？時々、Javascriptでは表すことのできないSOAP services（名）があります。このようなケースでも最初のフォームはサービス名が何であろうと常に動作するシステムを提供してくれるからなのです。

* Section 4: Querying a WsdlService Object

サービスオブジェクトが手に入ったので、これを使って実現していきます。ここで”getOperationNames”メソッドが役に立ちます。メソッドの呼び出しとログ結果の取得について確かめておきます。

Logger.log(geoService.getOperationNames());

上記の戻り値は[GetGeoIP, GetGeoIPContext]です。予想通りオリジナルのWebservicesXページ上のリストにあるオペレーション名と同じ名前のものです。こうなると"enables you to easily look up countries by IP addresses."といったドキュメントのある”GetGeoIP”メソッドを呼び出したくなるでしょう。

* Section 5: Creating Web Service Paramaters

目的のオペレーションが見つかったので、はじめてのウェブサービスを呼び出してみます。この段階では、ウェブサービスが現在どのように呼び出されているかを知ることが重要です。そして、ここでは外部のSOAPツールをひとつ選んで使うことができます。また、幸いWebserviceXは実行できるウェブサービスのデモンストレーションページを備えているのでこれを利用することも可能です。 ”GetGeoIP”の実行はWebservicesXのオリジナルページから固有のオペレーションページへ移動する必要はありません。このページのままあなた自身のIP addressをプラグインするか”72.14.228.129”のようなサンプルアドレスを利用して確かめられます。
”WebserviceX”のデモ用ページ上で、ウェブサービスがメッセージと共に呼び出されたことを示す下のようなドキュメントを見ることができます。

  POST /geoipservice.asmx HTTP/1.1
  Host: www.webservicex.net
  Content-Type: text/xml; charset=utf-8
  Content-Length: length
  SOAPAction: "http://www.webservicex.net/GetGeoIP"

  <?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
      <GetGeoIP xmlns="http://www.webservicex.net">
        <IPAddress>72.14.228.129</IPAddress>
      </GetGeoIP>
    </soap:Body>
  </soap:Envelope>

通常これは、処理のための多くのインフラストラクチャです。でも大丈夫。”Soap library”がほとんどの面倒を見てくれるのです。ユーザーがすることは<soap:Body>タグを次のセクションに挿入することだけで、あとはライブラリーがやってくれます。

   <GetGeoIP xmlns="http://www.webservicex.net">
      <IPAddress>72.14.228.129</IPAddress>
    </GetGeoIP>

このXMLのスニペットを生成するために幾つかのメソッドが用意されています。下のコードを利用できます。

var param = Xml.element("GetGeoIP", [
                Xml.attribute("xmlns", "http://www.webservicex.net"),
                Xml.element("IPAddress", [
                  "72.14.228.129"
                ])
              ]);

XML作成の詳細はこちら”Xml Documentation” です。

* Section 6: Testing a Soap Operation

ウェブサービスへ渡すパラメーターができたら、サービスオブジェクトであるデバッグメソッドの'getSoapEnvelope'を利用してそれが正しいメッセージかどうかの検証ができます。このメソッドは操作の各段階でインターネット上のサービスへ実際にメッセージを送ることなく動作します。デバッグや微調整が必要な場合に何が生成されているのか知ることができるのです。次のように試して結果をチェックできます。

  var envelope = geoService.getSoapEnvelope("GetGeoIP", param)
  Logger.log(envelope);

ログは下のように表示されているはずです。

 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                     xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
      <GetGeoIP xmlns="http://www.webservicex.net">
        <IPAddress>72.14.228.129</IPAddress>
      </GetGeoIP>
    </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

これは上記のXMLとまったく同じものです。（ネームスペースの決め方の多少の違いを除いて）これらによってメッセージが正しいこと、そして、いよいよサービスを呼び出す最終段階に到達したことになります。

* Section 7: Invoking a Soap Operation

ウェブサービスを呼び出すメソッドは２つ用意されています。下の２つのうちどちらも呼び出せる例です。

  var result = geoService.invokeOperation("GetGeoIP", [param]);

var result = geoService.GetGeoIP(param);

前述のgetServiceで説明の通り、呼び出しのためのメソッド名はWSDLファイルの情報から簡単に自動生成できます。後者の形式はコードが簡単で手間をかけずにサービスを呼び出すことができます。しかしながら、操作名のJavaScript表記が無理な場合、前者のコードなら常に呼び出すことができるようになっています。

* Section 8: Working with a Soap Operation Result

SOAPオペレーションを呼び出すことができたので提供された結果を利用してみましょう。 SAOPシステムはXMLにメッセージを渡すためのものですから、当然結果もXMLで返ってきます。 XMLを見るためには下のようにデバッグ用メソッドの'toXmlString'を使います。

Logger.log(result.toXmlString());

そして、次のようなログに出会うでしょう。

 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  <GetGeoIPResponse xmlns="http://www.webservicex.net">
    <GetGeoIPResult>
      <ReturnCode>1</ReturnCode>
      <IP>72.14.228.129</IP>
      <ReturnCodeDetails>Record Found</ReturnCodeDetails>
      <CountryName>UNITED STATES</CountryName>
      <CountryCode>US</CountryCode>
    </GetGeoIPResult>
  </GetGeoIPResponse>

要求している情報はIP アドレスの国別コードです。これを手に入れるためには、返されてきたXMLオブジェクトに普通に”ドット(dot)”を入れてあげるだけです。

Logger.log(result.Envelope.Body.GetGeoIPResponse.GetGeoIPResult.CountryCode.Text);

これらの重宝なプロパティーはXMLのライブラリーが生成してくれます。こうして、タグ名を持つネストした要素に到達することが可能となり、"テキスト"プロパティを使用してXML要素のテキストの内容を取得することができます。
XMLのドキュメントに簡単にアクセスするためのすべての情報は”Xml Documentation”を参照してください。上のコードの結果”US”が返されていることを確かめてください。

* Summary and Complete Code

ここまでで完了です。ほんの数ステップでした。
これで任意のIPアドレスからそこの国へ行くことができます。下に完全なコードを掲載しておきます。

 function determineCountryFromIP(ipAddress) {
    var wsdl = SoapService.wsdl("http://www.webservicex.net/geoipservice.asmx?wsdl");
    var geoService = wsdl.getGeoIPService();

    var param = Xml.element("GetGeoIP", [
                  Xml.attribute("xmlns", "http://www.webservicex.net"),
                  Xml.element("IPAddress", [
                    ipAddress
                  ])
                ]);

    var result = geoService.GetGeoIP(param);
    return result.Envelope.Body.GetGeoIPResponse.GetGeoIPResult.CountryCode.Text;
  }

ここでは取り敢えず、SOAPサービスを呼び出して結果を処理するところまでを簡単に追ってみました