Google Apps Script Documentation - Soap Services

Soap Overview

現在”SOAP”は” Simple Object Access Protocol ”の略として知られています。XMLをベースとしたウェブサービスへアクセスするためのプロトコルです。標準のHTTPプロトコルを介して異種システム間が相互に接続することを可能にします。

新しい”Google Apps Scrip”の機能はソープ関数（オペレーションとして知られています）への呼び出しを構築し、XMLの戻り値の解析を容易にします。 SOAPを利用した”Google Apps Scrip”を始めるにあたあっては、目標とするサービスについての基本情報が必要です。
それらはWSDLフィル（Web Services Definition Language）というかたちにまとめられています。
定義付けされたサービスは、Apps ScriptがSOAPオペーレーション（Apps Scriptの関数やメソッドのスクリプトでに似ています）を起動するために必要なすべての詳細を提供しています。 WSDLファイルは一般的に、そのサービスに関連付けられているURLで提供されています。

WSDLファイルがオペーレーション（関数/メソッド）の詳細を提供します。そしてサービスが提供されると、各オペレーションを呼び出すために必要なパラメータを設定します。
Appsスクリプトは要求を自動的にパッケージ化してオペレーションを呼び出します。そして、大量のエラーコードの可能性を避けながらサービスからの応答を展開してくれます。

Soap Walkthrough

Google Apps ScriptからSOAPを使うためには実行のための共通ステップがあります。下のリストから実際の動きを確かめることができます。

Soap サービスの利用に当たっては、先ずはじめにサービスの内容を記述したWSDLファイルのアドレスが必要になります。このWebアドレスは、インターネット上でSOAPサービスにアクセスするために使われるWSDLファイルとして作られることが必要です。（イントラネット上ならばSDCが有効になっていること） (example)
Wsdlオブジェクトが作成されれば、関連するサービス名を見つけるための照会が可能になります。 (example)
要求するサービス名が見つかると、そのサービスを記述したWsdlサービスオブジェクトがWsdlオブジェクトから呼び出されます。 (example)
Wsdlサービスオブジェクト取得後、利用可能なSoapオペレーション名が見つかります。 (example)
一般的にはウェブサービスを呼び出すためにはリクエストに引数を与える必要があります。 (example)
SoapオペレーションがWsdlサービスへの呼び出しを打ち切るにはいくつかの方法があります Soapのエラーを診断するためのデバッグメソッドが用意されています。 (example)
Soapオペレーションの呼び出しは結果としてXmlElementを返します。必要に応じてこれらを照会したり操作することができます。 (example)

Shorthand Xml

SoapではXMLが頻繁に使われるので、AppsScriptはXMLドキュメントの作成のためのshorthandを提供しています。shorthandは添付のチュートリアルで示したXMLオブジェクトと同じ意味で使用することができます。実際に意識して利用すれば、ドキュメントの内容や手順の作成の方に集中することができます。 shorthandではJavaScriptの配列をXML要素に使用することができます。またJavascriptの連想配列（マップまたはオブジェクト）は属性に使用することができます。

次のXMLスニペットを作成してみましょう :
<GetGeoIP xmlns="http://www.webservicex.net"> <IPAddress>{ipAddress}</IPAddress> </GetGeoIP>
{ipAddress}は実行時に指定する動的な値です。

このXMLスニペットを構築するデフォルトの方法はこのようになります：
var param = Xml.element("GetGeoIP", [ Xml.attribute("xmlns", "http://www.webservicex.net"), Xml.element("IPAddress", [ ipAddress ]) ]);

しかしこれをshorthandを利用すれば次のように書き換えることができます：
var param = [ "GetGeoIP", { "xmlns" : "http://www.webservicex.net" }, [ "IPAddress", ipAddress ] ];

このshorthandのフォーマットは次のようになっています；

XmlElementsはJavascriptの配列のはじめの位置の文字列で表示される。この文字列の値は変換された要素のタグ名となる。
配列内の以後のすべての要素は、次のルールに従ってXmlElementの子となる。
文字列に文字列をマップする連想配列はXmlElementを含むXmlAttributesに変換される。連想配列内のキーは属性名と後に属性値となる連想配列内の属性値になる。
配列の子供が最初のルールに一致する場合は、自身が繰り返しXmlElementの子供に変換される。
文字列に変換された他のすべての子供たちは、XmlElementに含まれているXmlTextの子供として格納される。

Soap Headers

SOAPサービスはSOAP操作と共に送信される追加情報が必要になることがあります。たとえば、ある種のSOAPサービスでは、リクエストの特別なヘッダセクションで送信されるための認証パラメータが必要となることです。追加の引数を渡すことによって、SOAPサービスでは呼び出しのなかで下のようにこの情報を渡すことができます。

  var header = Xml.element(...);
  var result = geoService.GetGeoIP(param, header);

実際にメッセージを送信する前に、それがどのような内容なのかを確認するためにgetSoapEnvelopeメソッドが下のように使用されます。

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

Accessing Intranet Services

もしイントラネット上だけのSOAPサービスを備え、すでに企業用のSDCを構築済ならば、GoogleWebScriptからSOAPサービスにアクセスすることができます。下の例のようにSoapService.wsdlのuseIntranetパラメータにtrueを渡すことによって可能です。

var wsdl = SoapService.wsdl(wsdlAddress, true);

これ以降はすべてのネットワーク通信が、SDC上で企業内部のSOAPサービスにアクセスできるように実行されます。

Soap Services Overview