SharePointのGetListitemで値を取得する

SharePointには、リストから任意の値を抽出するWebサービスが標準で用意されています。Lists.asmx の、「GetListItem」メソッドです。

以下は、このWebサービスを、JavaScriptで利用するサンプルになります。知っていれば、いざという場合にいろいろと応用が効くWebサービスです。

まず、サービスの仕様については、こちらにドキュメント(英語)があります。
Lists.GetListItems Method (Lists)

サービスのURLは http://Server/_vti_bin/Lists.asmx です。このアドレスにクエリを送信しますが、その書式は以下のとおり。

—–」の部分が設定の必要な値になります。

[code]<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="hvttp://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><GetListItems xmlns="http://schemas.microsoft.com/sharepoint/soap/"><listName>1.—–</listName><viewName>2.—–</viewName><query><Query><Where><Eq><FieldRef Name="3.—–" /><Value Type="4.—–">5.—–</Value></Eq></Where></Query></query><viewFields><ViewFields><FieldRef Name="6.—–" /><FieldRef Name="6.—–" /><FieldRef Name="6.—–" /></ViewFields></viewFields><rowLimit>7.—–</rowLimit><queryOptions><QueryOptions/></queryOptions><webID></webID></GetListItems></soap:Body></soap:Envelope>[/code]

1.—–
リストのGUIDです。{E405E394-0F60-4586-AB2E-952356D50ACF} など。{} は省略しても大丈夫なようです。また、リストに設定された「名前」でも大丈夫です(日本語可)。

2.—–
ビューのGUIDです。同じく{} は省略しても大丈夫なようです。この値が null の場合、自動的に既定のビューが選ばれます。

3.—–
クエリでアイテムを特定するのに利用する列名(内部名)。タイトル列は “Title” 、ID列は “ID” です。ひとつしか指定出来ません。

4.—–
3で指定した列の形式です。これはSharePoint既定で次のように決まっています。タイトル列は “Text” 、ID列は “Number” です。

・テキスト(Text)
・改行テキスト(Note)
・選択肢(Choice)
・数値(Number)
・通貨(Currency)
・参照(Lookup)
・はい/いいえ(Boolean)
・URLまたは画像(URL)
・日付と時刻(DateTime)
・集計値(Calculated)

5.—–
クエリでアイテムを特定するための値で「完全一致」である必要があります。例えば、クエリ値が “demo” である場合、”demo1″ “demo_demo” は対象外です。ただし、値が数値である場合、<Eq></Eq>以外に、次のオプションがあります。

・<Lt></Lt> クエリ値「以下」
・<Gt></Gt> クエリ値「以上」

また、<query><Query><Where>~</Where></Query></query>の間を<And></And>や<Or>で挟むことで、複数の条件を設定することが出来ます。

以下のように書けば、「Title が A または B」になります。

<query><Query><Where><Or><Eq><FieldRef Name=”Title” /><Value Type=”Text”>A</Value></Eq><Eq><FieldRef Name=”Title” /><Value Type=”Text”>B</Value></Eq></Or></Where></Query></query>

6.—–
値を取得したい列の内部名です。<FieldRef Name=”ColA” /><FieldRef Name=”ColB” /><FieldRef Name=”ColC” /> のように、いくつでも指定出来ます。

7.—–
取得する最大件数(行数)です。<rowLimit>1000</rowLimit> で「最大1000アイテム」になります。

以上を駆使することで、複雑な条件のクエリを組みてることが可能です。

次に、サービスから返される値ですが、次のようなXML構文になっています。指定した列値は z:row の属性として含まれますが、このとき、属性名が「ows_ColumName」になる点がポイントです。この ows_ は検索インデックス時のプロパティでも同様なのですが、何の略なのか?そもそも何故必要なのかはよく判りません。

/soap:Envelope
  /soap:Body
    /GetListItemsResponse
      /GetListItemsResult
        /listitems
          /rs:data
            /z:row

例として、次のリストに対してクエリを送信します。

とりあえず、スクリプトを組み立てて、コンテンツエディタWebパーツのソースに仕込みます。ただし、検証を目的にある程度汎用性をもたせたところ、無駄に長くなってしまいました。このスペースに乗せると訳がわからないので、テキストで外出しします。

サンプル1 20100228sample1.txt

「タイトルが B のアイテムの colA colB 列を最大2件」という条件で、以下が返りました。

確かにニ件ですが、どこか変です。上のリスト(ちなみに既定ビューに設定されています)であれば、もし「B」で走査をかけたのなら、まず「ZZZ」が、次に「MNO」という結果になる筈です。しかし、実際には「JKL」がヒットしています。

ためしに、リスト側をID値でソートしてみました。

これなら、結果と整合します。どうやら、GetListItem による走査は、ID順に行なわれるようです。この仕様は、時としてやや不便かもしれません。

なお、クエリ結果のXML文は次のようになっています。実際には、明示的に指定した「colA」「colB」以外にも、様々な情報が含まれているようです。

<z:row xmlns:z=”#RowsetSchema” ows_colA=”JKL” ows_colB=”4.00000000000000″ ows_MetaInfo=”4;#” ows__ModerationStatus=”0″ ows__Level=”1″ ows_Title=”B” ows_ID=”4″ ows_owshiddenversion=”4″ ows_UniqueId=”4;#{ED0FA638-4AAE-4AD7-BABA-123C9AF235F0}” ows_FSObjType=”4;#0″ ows_Created=”2010-02-24 23:56:59″ ows_FileRef=”4;#Lists/GetListItem/4_.000″/>
<z:row xmlns:z=”#RowsetSchema” ows_colA=”MNO” ows_colB=”3.00000000000000″ ows_MetaInfo=”5;#” ows__ModerationStatus=”0″ ows__Level=
“1” ows_Title=”B” ows_ID=”5″ ows_owshiddenversion=”5″ ows_UniqueId=”5;#{EE527A93-74D3-4957-A17E-B92D54DBE2C1}” ows_FSObjType=”5;#0″ ows_Created=”2010-02-24 23:57:00″ ows_FileRef=”5;#Lists/GetListItem/5_.000″/>

行数を指定しなかった場合、以下の結果が返ります。


サンプル2 20100228sample2.txt

が。ここまで説明しておいてナンなのですが。実は、もっと手軽で、むしろより応用の効く設定方法があります。

1.ビューのGUIDを明示的に指定する。
2.<query></query>を記述しない
3.<FieldRef Name=”” />を記述しない
4.<rowLimit></rowLimit>はnull

これにより、以下のようなクエリ構文になります。

<?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><GetListItems xmlns=”http://schemas.microsoft.com/sharepoint/soap/”><listName>{18248EA9-9DA3-462C-84BB-A26C1B27E7FB}</listName><viewName>{A2120531-CC25-4565-8E0E-8CCA3316C557}</viewName><rowLimit></rowLimit><queryOptions><QueryOptions/></queryOptions><webID></webID></GetListItems></soap:Body></soap:Envelope>

例として、次のようなビューを設定してみした。「colB が5以上」でフィルタをかけており、ソートもID順では有りません。

以下、クエリの実行結果です。長いですが、きちんとビューに設定されたソート順で、表示されている列を取得しています。やはり、表示していない列も含まれてしまいますが、これはご愛嬌(?)

サンプル3 20100228sample3.txt

0:
ows_ID (6) ows_LinkTitle (B) ows_colA (PQR) ows_colB (6.00000000000000) ows_colC (たちつ) ows_MetaInfo (6;#) ows__ModerationStatus (0) ows__Level (1) ows_Title (B) ows_owshiddenversion (7) ows_UniqueId (6;#{A702CCFE-93DD-40D0-8EAB-79D7FF71396C}) ows_FSObjType (6;#0) ows_Created_x0020_Date (6;#2010-02-24 23:57:01) ows_Created (2010-02-24 23:57:01) ows_FileLeafRef (6;#6_.000) ows_FileRef (6;#Lists/GetListItem/6_.000)
1:
ows_ID (8) ows_LinkTitle (C) ows_colA (VWX) ows_colB (6.00000000000000) ows_colC (あいう) ows_MetaInfo (8;#) ows__ModerationStatus (0) ows__Level (1) ows_Title (C) ows_owshiddenversion (6) ows_UniqueId (8;#{E0156215-ADC1-4DC9-8FB0-39AE0B254B17}) ows_FSObjType (8;#0) ows_Created_x0020_Date (8;#2010-02-24 23:57:03) ows_Created (2010-02-24 23:57:03) ows_FileLeafRef (8;#8_.000) ows_FileRef (8;#Lists/GetListItem/8_.000)
※略
6:
ows_ID (1) ows_LinkTitle (A) ows_colA (ABC) ows_colB (9.00000000000000) ows_colC (すせそ) ows_MetaInfo (1;#) ows__ModerationStatus (0) ows__Level (1) ows_Title (A) ows_owshiddenversion (6) ows_UniqueId (1;#{1AB5A494-01AB-4914-9D91-0C66ED0576F9}) ows_FSObjType (1;#0) ows_Created_x0020_Date (1;#2010-02-24 23:56:57) ows_Created (2010-02-24 23:56:57) ows_FileLeafRef (1;#1_.000) ows_FileRef (1;#Lists/GetListItem/1_.000)
7:
ows_ID (9) ows_LinkTitle (D) ows_colA (WZA) ows_colB (9.00000000000000) ows_colC (こさし) ows_MetaInfo (9;#) ows__ModerationStatus (0) ows__Level (1) ows_Title (D) ows_owshiddenversion (5) ows_UniqueId (9;#{15C855C3-4A06-468B-A627-8753058E2DF0}) ows_FSObjType (9;#0) ows_Created_x0020_Date (9;#2010-02-24 23:57:05) ows_Created (2010-02-24 23:57:05) ows_FileLeafRef (9;#9_.000) ows_FileRef (9;#Lists/GetListItem/9_.000)

つまりGetListItemは、リストとビューだけGUIDで指定すれば、実は「あとは不要」という仕様なのです。個人的にはかなり衝撃的な事実でしたが、実はこれ、MSDNにはきちんとそう書いてあるんですよね…取説はよく読みましょう、ということでしょうか(苦笑)

Lists.GetListItems Method (Lists)
A string that contains the GUID for the view surrounded by curly braces ({}), which determines the view to use for the default view attributes represented by the query, viewFields, and rowLimit parameters. If this parameter contains an empty string, the default view is used. If the view GUID is supplied, the value of the query, viewFields, or rowLimit parameter overrides the equivalent setting within the view. For example, if the view specified by the viewFields parameter has a row limit of 100 rows but the rowLimit parameter contains 1000, then 1,000 rows are returned in the response.

GetListItemで大量の行列情報をエクスポートする
Special Tanks to mojalog
SharePointのGetListItemsを使ってみました
SharePointのLists.asmxのGetListItemsの条件句XML


Author

中村 和彦(シンプレッソ・コンサルティング株式会社 代表)が「ユーザ視点の SharePoint 情報」を発信します。元大手製造業 SharePoint 運用担当。現SharePoint コンサルタント。お仕事のお問い合わせはこちらまでお願いします。当ブログにおける発信内容は個人に帰属し所属組織の公式発信/見解ではありません。
FB : 中村 和彦
blog: Be・Better!
MS MVP SharePoint 2009/10-2011/9
MS MVP Office 365 2012/10-2014/9