SharePoint Webサービスを始めましょう

SharePointはWebサービス一式を通じて互換性と遠隔オペレーションをサポートしますが、ここでいうSharePointはWSS 3.0（Windows SharePoint Services）とMOSS 2007（Microsoft Office SharePoint Server）のことです。プログラムに基づいてSharePointにアクセスするには、WebDAVに加えて、オブジェクトモデルやWebサービス、HTTP上のRPCなど、多数のやり方があり、アプリケーションのニーズに応じて、それぞれにメリットと使うべき場所があります。SharePoint RPCプロトコルは有用かつ強力になり得ますし、特にコンテンツの追加となると、確かに威力を発揮します。オブジェクトモデルはWebサービスに比べてずっと頑丈で機能が豊富ですが、遠隔オペレーションに対するサポートがないため、オブジェクトモデルを活用するには、コードをSharePointサーバー上で実行しなければならず、活用するには.NETコードを自分で書かねばなりません。管理用のスクリプトや、クライアントマシン上で動作中のアプリケーションや企業内の非SharePointアプリケーションのタスクなどでSharePointコンテンツを操作する必要があるなど、SharePointのデータを遠隔で扱う理由は多種多様にあります。SharePoint Webサービスはオブジェクトモデル上に構築され、オブジェクトモデルで利用可能な機能のサブセットを公開しており、遠隔オペレーションが可能で、Webサービスの消費をサポートするいかなる言語およびプラットフォームの使用も可能にします。SharePointと一緒に出荷されるWebサービスは、ほとんどのタスクをこなすには十分ですが、Webサービスでは表面化していないオブジェクトモデルのオペレーションが必要となる可能性もあり、その場合はカスタムのWebサービス実装によりWebサービスを拡張する必要があるでしょう。この記事では、WSS3とMOSS 2007に難しい設定など一切せず、すぐに利用可能なWeb サービスと、Javaと.NETからそのWebサービスを消費する方法に目を向けます。

Webサービスアーキテクチャの概要 

SSとMOSSの相違を詳細に説明している非常に優れた記事が多数存在するため、Webサービスとの関連で必要とされる場合を除き、相違には触れないつもりです。MOSS 2007はWSS 3.0上に構築されており、そのWSS 3.0もASP.NET 2.0上に構築され、IIS（Internet Information Server）で動作するということを覚えておきましょう。IISとASP.NETを確実に理解することが重要であり、SharePointの取り扱いと理解はその遥か先に位置します。これから検討するSharePoint Webサービスの大多数がWSS 3.0に含まれていますが、進化版のエンタープライズ検索機能など、MOSS 2007同梱の追加機能を活用可能にするため、MOSS 2007に入っている付加的なWebサービスもいくつかあります。

SharePoint WebサービスはASP.NET Web Services（ASMX）に実装されており、こうしたWebサービスの大部分について、その物理的ファイルは「Microsoft Shared」ディレクトリ内の「web server extensions\12\ISAPI」の項目にあり、この項目は通常、「C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\ISAPI」にあります。Central Administrationツール用のadmin WebサービスはADMISAPIフォルダにあり、このフォルダ向けにcentral administrationコンソールには「_vti_adm」という名称の仮想ディレクトリが入っています。SharePointサイトが作成されると、その中には「_vti_bin」という名称の仮想のディレクトリが入り、このロケーションを示すようになっています。IISにはサブwebのためのアプリケーションや仮想ディレクトリはありませんが、SharePointメタデータとHttpModulesを介して_vti_bin仮想のディレクトリへのマッピングは含まれています。

各サービスについて*.wsdl.aspx ファイルがあり、このファイルはサービスWSDL（Web サービス記述言語）を生成し、*.disco.aspxがサービス発見の実装と実際の*.asmxエンドポイント・ファイルを提供しますが、ファイルの大部分には、SharePointアセンブリを参照するページ命令と、サービス向けの実際の実装を含んだ型が入っているだけです。

設定せずにすぐ使えるサービス

SharePointにはすぐに使える実装されたWebサービスが多数あり、管理タスクからリスト化されたデータの操作等々、一般的なタスクや基本的なタスクの大部分に対応します。以下はSharePoint Webサービスの一覧ですが、参考までに機能のあらましをつけました。こうしたシンプルな拡張版リストがあれば、利用可能な全サービスとメソッドが簡単に分かり、Webサービス操作時に役立ちます。

クエリサービスの消費

これでSharePoint Webサービスを理解できましたが、オーナーマニュアルを通して読んだ後に、さっと調べて始められるようなものではありません。ここではすべてのWebサービスについて深く掘り下げる時間はありませんし、また、その他については次の記事にとっておくことにします。SharePoint Webサービスの多数は、なぜかXML NodeあるいはXMLでコードされた文字列を取るか返すかしますが、残念ながら型付けされたスキーマの無いツールでは、これが何であるべきかを推論し、例のすてきなプロキシオブジェクトを生成することはできません。型付けされたスキーマの欠如に対処するため、Webサービスに文字列フォーマッティングを使った多数の実装を、私はこれまで見てきましたし、こうしたサービスから渡されて返されるXMLを記述するスキーマを長い間、広範囲にわたって探してきました。その結果、サービスに出入りして渡されたXMLとドキュメンテーションの組合わせから推定して、queryresponse.xsdを作成することになり、これにより、.NETユーザー向けにはxsd.exeを使い、javaユーザー向けにはJAXBを使って、クラス表現ができるようになりました。

注意: 前述したように検索用Webサービスには2種類あり、それはMOSS向けのsearch.asmxとWSS向けのspsearch.asmxです。両サービスのスキーマは非常に似通っていますが、MOSSを動作中のマシンで spsearch.asmxの呼び出しを試みると、MOSSのより高度な検索機能を優先してWSSの索引作成およびクエリサービスが無効にされるため、例外処理が実行されてしまいます。

.NETを使った例

.NETからのSharePoint Webサービス消費はどちらかと言うと単純明快で、単にWebリファレンスを追加し、生成されたプロキシを使えばいいだけです。作成したXSDを活用するステップを加えて、送ったXMLをシリアライズし、返されたXMLをデシリアライズするために使用するクエリとレスポンスを表現するクラス一式を生成します。

Visual Studio 2005を設定してメニューにXSD.exeを追加する

Visual StudioにはXSD.exeというツールが入っており、XSDから.NET型を生成するために使うことができます。しかし、このツールはコマンドラインツールですから、私としてはVisual Studioにメニューオプションを追加し、IDEから実行するようにしたいのです。すでにこのメニューオプションを追加済みか、同様のことが可能なアドインの追加がお済みなら、このステップは読み飛ばして結構です。

1. Visual Studioの「Tools」メニューで「External Tools」ダイアログを開きます
2. 「Add」をクリック
3. 必要なプロパティを設定後、「OK」をクリック

選択するXSDファイルをダウンロードする

検索リクエストとレスポンスのシリアライズ、デシリアライズをするために使ったプロキシクラスを生成するのに使用する予定のXSDファイルを、ここ(zip)からダウンロードしましょう。ダウンロードしたファイルを作業ディレクトリに解凍します。このファイルには完了したプロジェクトとともにXSDが入っています。

XSDからプロジェクトを作成し、.NET型を作成します。すでにXSDがあるため、ダウンロードしたXSDからWindows Formsプロジェクトを作成し、.NET型フォームを生成します。Microsft.Search.Query.xsdを開いたら、ツールメニューに行き、直前のステップで作ったXSDメニュー項目を選び、Microsoft_Search_Query.csファイルを生成します。

Webリファレンスを追加する

検索WebサービスにWebリファレンスを追加することから始めますが、それには「solution explorer」（ソリューション・エクスプローラー）ウィンドウでプロジェクト用の「references」（リファレンス）ノードを右クリックします。そこで「Add Web Reference」（Webリファレンスを追加する）を選び、「http:///_vti_bin/spsearch.asmx」をURLテキストボックスに入力したら、「Go」をクリックします。SharePointサーバーにログインするよう指示メッセージが出ることもありますが、これでSharePointサービスがサポートするメソッドのリストが出るはずです。「Web Reference Name」（Webリファレンス名）向けに「SPSearch」を追加し、「Add Reference」（リファレンスを追加）をクリックします。

生成プロキシをサブクラス化する

さらに事を単純化するために、生成したプロキシを独自にサブクラス化します。そうすれば、QueryServiceのラップが可能になり、XSDから生成したクラスを使って、Query（クエリ）メソッドに渡されて返されたXMLのバリデーション、シリアライゼーション、デシリアライゼーションを隠すことができます。

サービスを呼び出すアプリケーションを作成する

次に、クエリクラスとQueryServiceクラスのインスタンスを単に生成して、その後、QueryServiceクラス上でクエリオブジェクトをQueryメソッドに渡します。

SPSearch.QueryService search = new SPSearch.QueryService();
Microsoft_Query_Request request = new Microsoft_Query_Request();
search.Query(request);

Javaを使った例

avaからのSharePoint Webサービス消費に大きな違いはなく、根本的なステップは同じであり、提供されたXSDクラスを生成し、Webサービスプロキシを生成後、アプリケーションを構築します。javaからSharePoint Webサービスを消費する際に直面する難題の大部分は、認証とSharePoint Webサービス内でのDataSetの使用です。Webサービス操作を単純化するJava IDEが多数利用可能ですが、私は最近主に.NETを扱っているため、SDKを利用する例をお見せし、IDEの選択については読者にお任せすることにしましょう。

注意: この例では、J2SE 6.0 Update 3を使って構築とテストを行いました

Java SharePointのサンプルプロジェクトのディレクトリとルートファイル

サンプルを構築して走らせるためのバッチファイル２個と一緒に、完全なプロジェクトと生成ファイル(zip)が含まれています。走らせるためには、ご自分のJDK binフォルダ向けにホームディレクトリで「xjc-build.bat」と「build-run.bat」を修正し、そして構築と実行を行う前に、サーバー設定（エンドポイント、ユーザー名、パスワード）でwsspsample/Main.javaを編集する必要があるでしょう。

Service WSDLをインポートする

私はSharePointサーバーから自分の開発マシンにWSDLを取り込むことから始めますが、これには2つの理由があります。ツールを適切に扱うために、ADO.NETデータセットを使うあらゆるWSDLを修正する必要があります。また、SharePointサーバー上でWSDLへアクセスするには、一般に認証が必要で、Javaが生成したプロキシはコンストラクタにWSDLを要求するため、認証が少々厄介になります。

Search WSDLを取り込む

Windows SharePoint Services 3.0検索サービスでは、Internet Explorerを開き、そしてError! Hyperlink reference not valid.（エラー！ ハイパーリンクリファレンスが無効です）に行き着いたら、File|Save As...からspsearch.wsdlとしてそのページを作業ディレクトリに保存します。MOSS 2007を扱っている場合は、Error! Hyperlink reference not valid（エラー! ハイパーリンクリファレンスが無効です）を使うことになるでしょう。

Search WSDLを修正する

MOSS 2007のGetSearchMetaDataメソッド同様、QueryExメソッドはADO.NETデータセットを返します。ADO.NETデータセットは動的にバインドされ、WSDLのスキーマ特性に周期的なリファレンスを使ってWSDLで表現されますが、これはJAXB wsimportツールで少々問題を起こします。Java JDKの前のバージョンではうまく機能する回避策を発見しましたが、私が使っていたバージョンではうまく行きませんでした。その代わりに、次のようにWSDLを修正することにしました。そのためにはメモ帳でWSDLを開き、「s:schema」のインスタンスを検索し、スキーマの「element」要素でリファレンスとして用いられていたところを修正し、周期的なリファレンスを削除し、スキーマには「any」要素を残しました。

<s:sequence>
     <s:element ref="s:schema"/>
     <s:any/>
</s:sequence>  
     

<s:sequence>
     <s:any minOccurs="0" maxOccurs="unbounded"/>
</s:sequence>

WSDLをインポートする

これでローカルにWSDLが準備でき、修正も済んだので、JAXB wsimport.exeツールを使ってプロキシクラスを生成できます。

wsimport -p wsspsample.webref.spsearch -keep spsearch.wsdl
wsimport -p wsspsample.webref.search -keep search.wsdl

アプリケーション用に生成したコードを微調整できるように、インポートに-keepフラグを使ってjavaコードを保持します。ツールが生成するコードには絶対パスがついているため、別のディレクトリにアプリケーションを移動し、アプリケーションと一緒にWSDLを記憶させるつもりなら、「webref\search\QueryService.java」URLを修正して自らURLを作成しなければなりません。そうするには、単にWSDLへの絶対パスを削除し、代わりに相対パスを使用します。

url = new URL("file:search.wsdl");

Requestクラス、Responseクラスを生成する

RequestクラスおよびResponseクラスの生成には、私が作成した4つの「Microsoft.Search」XSDとJAXB xjc.exeツールを使う必要があります。以下では単に、パッケージレベルの注釈の生成を抑制し、目標パッケージを指定すれば、ツールがクラスを作成してくれます。

xjc -npa -p wsspsample.xom.query -d . Microsoft.Search.Query.xsd
xjc -npa -p wsspsample.xom.response -d . Microsoft.Search.Response.xsd

生成されたクラスを使う

QueryServiceのQueryサービスプロキシに加え、Queryメソッドへ渡されて、戻されたQueryとResponseのパケットについて、クラス表現が存在します。これをアプリケーションに使用する時がやってきました。まず、QueryServiceインスタンスを作る必要があり、このオブジェクトのコンストラクタがWSDLのローカルコピーを取ってきて、設定をロードすることになっています。QueryServiceインスタンスから、getQueryServiceSoapメソッドを使ってQueryServiceSoapインスタンスを取り出します。qsp変数の処置と同様に、QueryServiceSoapリファレンスを保持しておいて使う必要があるので、ご注意ください。というのも、getQueryServiceSoapメソッドが新しいインスタンスを返すと思われるからです。次にここのエンドポイントアドレスを、WSDLに含まれている以外のものに修正し、アプリケーションをいっそう動的にして、WSDLで設定された以外のSharePointサイトやSubSiteに接続できるようにします。

QueryService qs = new QueryService();
QueryServiceSoap qsp = qs.getQueryServiceSoap();

BindingProvider bp = (BindingProvider)qsp;
//bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "Administrator");
//bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "pass@word1");
bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
"http://barbie/_vti_bin/spsearch.asmx");

では、クエリをシリアライズし、そしてレスポンスパケットをデシリアライズするメソッドを作成しましょう。

public static String SerializeQuery(QueryPacket qp)
{
     try
     {
         JAXBContext jc =JAXBContext.newInstance("wsspsample.xom.query");
         Marshaller ma = jc.createMarshaller();
         ma.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT,Boolean.TRUE);
         ByteArrayOutputStream os = new ByteArrayOutputStream();
         ma.marshal(qp, os);
         return os.toString();     
     }
     catch(JAXBException ex)
     {
         return "";
     }
 }
 public static ResponsePacket DeserializeResponse(String s)
 {
     try
     {
         JAXBContext jc = JAXBContext.newInstance("wsspsample.xom.response");
          Unmarshaller um = jc.createUnmarshaller();
         StreamSource source = new StreamSource(new StringReader(s));
          return (ResponsePacket)um.unmarshal(source);
     }
     catch (JAXBException ex)
     {
         return new ResponsePacket();
     }
 }

ここからは単に、QueryPacketと必要なクラスを作成し、値を設定してサービスを呼び出します。

// Create a Search Query Packet Object
QueryPacket qp = new QueryPacket();
QueryType qt = new QueryType();
ContextType ct = new ContextType();
QueryTextType ctt = new QueryTextType();

ct.setQueryText(ctt);
qt.setContext(ct);
qp.setQuery(qt);

// Set search values
ctt.setValue("sharepoint");
ctt.setType("STRING");      //This is the default - not necessary
ctt.setLanguage("en-us");   //This is the default - not necessary

// Call the web service query
String sResponse = qsp.query(SerializeQuery(qp));

// Deserialize the response
ResponsePacket resp = DeserializeResponse(sResponse);

アプリケーションを構築して実行する

クエリリクエストとレスポンス向けに生成したWebサービスプロキシとオブジェクトモデルがあり、それを活用するアプリケーションもありますから、今度は幸運を祈りながら、構築し、実行し、テストする必要があります。SharePointサーバー装置が必要で、テスト用SharePointサーバーにMain.javaで使用する正確なエンドポイントアドレスを設定すべきであり、必要に応じてcredentialsも設定します。

参照およびリンク

Windows SharePoint Services 3.0 Web Servicesリファレンス(source)。

原文はこちらです：http://www.infoq.com/articles/swanson-moss-web-services
（このArticleは2008年2月6日に原文が掲載されました）