Lists.GetListItemChangesSinceToken メソッド (websvcLists)

[アーティクル]
02/02/2010

トークンに指定された日時以降にリストに対して行った変更を返します。

名前空間: websvcLists
アセンブリ: STSSOAP (stssoap.dll 内)

構文

'宣言
<SoapDocumentMethodAttribute("https://schemas.microsoft.com/sharepoint/soap/GetListItemChangesSinceToken", RequestNamespace:="https://schemas.microsoft.com/sharepoint/soap/", ResponseNamespace:="https://schemas.microsoft.com/sharepoint/soap/", Use:=SoapBindingUse.Literal, ParameterStyle:=SoapParameterStyle.Wrapped)> _
Public Function GetListItemChangesSinceToken ( _
    listName As String, _
    viewName As String, _
    query As XmlNode, _
    viewFields As XmlNode, _
    rowLimit As String, _
    queryOptions As XmlNode, _
    changeToken As String, _
    contains As XmlNode _
) As XmlNode
'使用
Dim instance As Lists
Dim listName As String
Dim viewName As String
Dim query As XmlNode
Dim viewFields As XmlNode
Dim rowLimit As String
Dim queryOptions As XmlNode
Dim changeToken As String
Dim contains As XmlNode
Dim returnValue As XmlNode

returnValue = instance.GetListItemChangesSinceToken(listName, viewName, query, viewFields, rowLimit, queryOptions, changeToken, contains)

[SoapDocumentMethodAttribute("https://schemas.microsoft.com/sharepoint/soap/GetListItemChangesSinceToken", RequestNamespace="https://schemas.microsoft.com/sharepoint/soap/", ResponseNamespace="https://schemas.microsoft.com/sharepoint/soap/", Use=SoapBindingUse.Literal, ParameterStyle=SoapParameterStyle.Wrapped)] 
public XmlNode GetListItemChangesSinceToken (
    string listName,
    string viewName,
    XmlNode query,
    XmlNode viewFields,
    string rowLimit,
    XmlNode queryOptions,
    string changeToken,
    XmlNode contains
)

パラメータ

listName
リストのタイトルまたは GUID のどちらかを含む文字列。UserInfo テーブルに対してクエリを実行するとき、文字列には UserInfo が含まれます。GUID を使用すると、パフォーマンスが向上します。

viewName
ビューの GUID を含む文字列。この GUID に基づいて、query、viewFields、および rowLimit パラメータによって表される既定のビュー属性で使用するビューが決まります。この引数を指定しなければ、既定のビューと仮定されます。この引数を指定した場合は、query、viewFields、または rowLimit パラメータの値が、ビュー内の同等の設定よりも優先されます。たとえば、viewFields パラメータで指定されたビューに、最大行数は 100 行までという制限があるとき、rowLimit パラメータの値が 1000 であると、応答では 1,000 行が返されます。

query
次の例に示すように、返されるレコードとその順序を決定するクエリを含む Query 要素。この要素は System.Xml.XmlNode オブジェクトに割り当てることができます。
```
<Query>
   <Where>
      <Lt>
         <FieldRef Name="ID" />
         <Value Type="Counter">3</Value>
      </Lt>
   </Where>
</Query>
```
指定した場合、このパラメータの値は viewName パラメータで指定したビュー内のクエリ、またはリストの既定のビュー内のクエリのどちらかを上書きします。

メモ :

クエリパラメータは、contains パラメータと共に使用するためのものではありません。

メモ :
クエリパラメータは、contains パラメータと共に使用するためのものではありません。

viewFields
次の例に示すように、クエリで返されるフィールドとその順序を指定する ViewFields 要素。この要素は System.Xml.XmlNode オブジェクトに割り当てることができます。

<ViewFields>
   <FieldRef Name="ID" />
   <FieldRef Name="Title" />
</ViewFields>

指定した場合、このパラメータの値は、viewName パラメータによって指定されたビュー内のビューフィールド、またはリストに対する既定のビュー内のビューフィールドよりも優先されます。この値が null であると、クエリによって、返される各アイテムに対してすべてのフィールドが返されます。

メモ :
PermMask フィールド (`<FieldRef Name="PermMask"/>`) を明示的に要求しない場合、一意のアイテムアクセス許可があるリスト対しては、GetListItemChangesSinceToken メソッドは失敗します。

rowLimit
ページングが開始される前にページ上に表示するアイテム数または行を指定する文字列。指定した場合、このパラメータの値は viewName パラメータで指定したビュー内で設定された行数の制限、またはリストの既定のビュー内で設定された行数の制限を上書きします。

queryOptions
XML フラグメント。SPQuery オブジェクトのさまざまなプロパティに対して個別のノードを含み、System.Xml.XmlNode オブジェクトに割り当てることができる次の形式を持ちます。

<QueryOptions>
   <IncludeMandatoryColumns>FALSE
      </IncludeMandatoryColumns>
   <DateInUtc>TRUE</DateInUtc>
</QueryOptions>

次の表に、queryOptions パラメータを介して渡される CAML (Collaborative Application Markup Language) フラグメントで使用することができる要素を示します。

要素	説明
DateInUtc	世界協定時刻 (UTC) 形式で日付を返す場合は TRUE、ISO 形式で日付を返す場合は FALSE。この要素は省略できます。既定値は TRUE です。
ExpandUserField	ユーザーフィールド値向けの特別なレンダリング。このレンダリングによって、値が、ログイン名、電子メール、SIP アドレス、およびタイトルに組み込まれます (これらが存在する場合)。このため、ユーザーフィールドはマルチルックアップフィールドとして動作します。展開で使用されるルックアップフィールドは、"Name"、"EMail"、"SipAddress"、および "Title" です。値は、「,#」で区切られます。ルックアップフィールド名に含まれるカンマは、「,,」としてエンコードされます。これらの値は、各アイテムの通常のフィールドデータに出現します。 <ExpandUserField>FALSE</ExpandUserField> looks like: ows_Author="1;#Admin AdminName" <ExpandUserField>TRUE</ExpandUserField> Looks like: ows_Author="1;#Admin AdminName,#login\name,#emailaddress,#sipaddress,#Admin AdminName "
ExtraIds	追加のアイテムを、返されるセットに含めるように要求します。このとき、追加のアイテムが変更されているかどうかは問題になりません。ExtraIds の一般的な使用例として、doclib にいるとき、doclib 全体ではなくフォルダに対して [接続…] を選択する場合に、同期するフォルダの ID を指定することが挙げられます。このような指定を行うことで、フォルダ名を取得し、そのフォルダ名がいつ変更されたかを判別することができます。メモ : この要素は、変更トークンでのみ使用してください。この要素を使用すると、クライアントは、1 つまたは複数のフォルダとの同期を実行し、階層上のフォルダが削除または名前変更されたことを検出できます。フォルダ名が返されるのは、リストに対して何らかの変更が行われ、変更されたアイテムを取得するクエリーでもフォルダの ID が使用されている場合のみです。例 <ExtraIds>1,4,23</ExtraIds>
Folder	指定したフォルダ内のアイテムに対してドキュメントライブラリアイテムをフィルタ処理するために使用される URL を指定します。この要素は省略できます。既定値は空の文字列です。
Paging	ページングをサポートする場合に必要となるデータを含む文字列 (ListItemCollectionPositionNext 属性など)。この要素が空のままである場合、返されるリストアイテムは、リストの先頭から始まるアイテムになります。クライアントアプリケーションは、サーバーが提供するブックマークの値を渡す必要があります。サーバーは、渡されたブックマークに基づいて、データの次のページを返します。この要素は省略できます。既定値は空の文字列です。changeToken と同様に、この要素を解析したり、作成したりしないでください。
IncludeAttachmentUrls	Attachments フィールドに対して返された値を、ブール値から完全な URL のリストに変更します。このリストは、「;#」で区切られます。
IncludeAttachmentVersion	IncludeAttachmentUrls と連動して使用されます。IncludeAttachmentVersion は、更新時の競合検出で使用される GUID とバージョン番号も返します。
IncludeMandatoryColumns	viewFields パラメータで指定されるフィールド (owsHiddenVersion、依存フィールド、必須フィールド) に加えて、必須のシステム列が返されることを指定する場合は TRUE。既定値は TRUE です。
IncludePermissions	個別のアイテムアクセス許可を要求する場合は、TRUE。
MeetingInstanceID	整数値。正の数は個別の会議インスタンスを表します。負の数は次の意味を持ちます - 3 = UnSpecified、-2 = AllWithSeries、-1 = AllButSeries、0 = Series。この要素は省略できます。既定値は -1 です。負の値は Microsoft.SharePoint.Meetings.SPMeeting.SpecialInstance 列挙体の値に対応します。
OptimizeFor	サポートされるのは、次の 2 つの値です。 ItemIds FolderUrls クエリまたは繰り返しの順番が要求されていない場合は、ItemIds が既定値になります。ItemIds は、ID の順番に基づいて、SQL クエリを最適化します。 FolderUrls は、DirName や LeafName の順番に基づいて SQL クエリーを最適化することにより、1 つまたは複数のフォルダのフラットコンテンツとして抽出された同期を最適化します。 <OptimizeFor>ItemIds</OptimizeFor>
RecurrenceOrderBy	一部の予定表プログラムに対する要件。定期的に発生する予定の場合、各予定に対して、マスタアイテムが最初に返され、その後ですべての例外が返されます。この順序は、内部で使用される特別な順序であり、他のすべての順序よりも優先して適用されます。メモ : プログラムで RecurrenceOrderBy を明示的に要求しない場合は、この要素を使用しないでください。ビューに Recurrence という種類のフィールドがある場合、リストは、定期的なアイテムのフィールドの定義に含まれている参照型の UID、EventType、および StartDate のフィールドに基づいて並べ替えられます。
RecurrencePatternXMLVersion	下位互換性を維持するために使用されます。RecurrencePatternXMLVersion は、バージョン内にのみ存在する要素を RecurrenceData フィールドが含んでいる場合に、このフィールドの値を変更して、<V3RecurrencePattern /> が返されないようにします。メモ : このタグがない場合、Windows SharePoint Services Version 2 に存在しない定期的なパターンは、<V3RecurrencePattern /> として送信されます。このタグが含まれているということは、Windows SharePoint Services 3.0 に対する新規の定期的なパターンが正確に送信されることを意味します。
ViewAttributes	GetView メソッドを使用してビューを取得するときに、View 要素の一部として返されるすべての属性を表す文字列。この要素はオプションで、既定値は空の文字列です。viewName パラメータを指定すると、永続的なビューのビュー属性が使用されます。このときに引数を指定すると、viewName パラメータによって指定された永続的なビューから取得できるすべてのビュー属性よりも、指定した引数が優先されます。この要素はオプションで、既定値は空の文字列であるので、ライブラリ内のすべてのドキュメントを返すには、ViewAttributes 要素を、「`<ViewAttributes Scope="Recursive" />`」のように使用します。

このパラメータに対してからの値を渡すには、次のように、空の QueryOptions 要素を含めます。

<queryOptions xmlns:SOAPSDK9=
      "https://schemas.microsoft.com/sharepoint/soap/" >
   <QueryOptions/>
</queryOptions>

changeToken
要求の変更トークンを含む文字列。この文字列に使用される書式の説明については、「概要 : 変更トークン、オブジェクトの種類、および変更の種類」を参照してください。null が渡されると、リスト内のすべてのアイテムが返されます。

contains
次の例に示すように、クエリ用のカスタムフィルタを定義し、System.Xml.XmlNode オブジェクトに割り当てることができる Contains 要素。
```
<Contains>
   <FieldRef Name="Status"/>
   <Value Type="Text">Complete</Value>
</Contains>
```
このパラメータには null を含めることができます。

戻り値

最後の変更トークンとアイテムの変更内容を返し、System.Xml.XmlNode オブジェクトに割り当てることができる XML フラグメント。次のような形式になります。

<listitems MinTimeBetweenSyncs="0" RecommendedTimeBetweenSyncs="180" MaxBulkDocumentSyncSize="500" 
   AlternateUrls="http://MyServer/,http://zinzinzin/" EffectivePermMask="FullMask" 
   xmlns:s="uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882" xmlns:dt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882" 
   xmlns:rs="urn:schemas-microsoft-com:rowset" xmlns:z="#RowsetSchema" 
   xmlns="https://schemas.microsoft.com/sharepoint/soap/">
   <Changes LastChangeToken="1;3;b0c07dce-e4c7-45a9-8b7f-0d5339f69633;633247934080930000;70853">
   </Changes>
   <rs:data ItemCount="2">
      <z:row ows_Attachments="0" ows_LinkTitle="MyItem1" ows_MetaInfo="3;#" ows__ModerationStatus="0" 
         ows__Level="1" ows_Title="MyItem1" ows_ID="3" ows_owshiddenversion="2" 
         ows_UniqueId="3;#{9153FDD3-7C00-47E9-9194-956BB20AAA8D}" ows_FSObjType="3;#0" 
         ows_Created_x0020_Date="3;#2007-08-31T21:34:59Z" ows_Created="2007-08-31T21:34:59Z" 
         ows_FileLeafRef="3;#3_.000" ows_FileRef="3;#sites/MyWebSite/Lists/MyList/3_.000" 
         ows_ServerRedirected="0" />
      <z:row ows_Attachments="0" ows_LinkTitle="MyItem2" ows_MetaInfo="5;#" ows__ModerationStatus="0" 
         ows__Level="1" ows_Title="MyItem2" ows_ID="5" ows_owshiddenversion="3" 
         ows_UniqueId="5;#{5BDBB1C0-194D-4878-B716-E397B0C1318C}" ows_FSObjType="5;#0" 
         ows_Created_x0020_Date="5;#2007-08-31T21:43:23Z" ows_Created="2007-08-31T21:43:23Z" 
         ows_FileLeafRef="5;#5_.000" ows_FileRef="5;#sites/MyWebSite/Lists/MyList/5_.000" 
         ows_ServerRedirected="0" />
         ...
   </rs:data>
</listitems>

備考

次の表では、戻り値パラメータについて説明します。

プロパティ	定義
MinTimeBetweenSyncs	ユーザーが開始する同期または自動同期の間隔を示す、最小時間数を表します。値は、時間を分単位で表したものです。メモ : クライアントは、ユーザーが同期を手動で開始する場合でも、この値を優先的に考慮する必要があります。つまり、この値が 5 分に設定されている場合は、ユーザーが [送受信] を繰り返しクリックしても、クライアントは 5 分ごとに 1 つの要求だけを送信する必要があります。
RecommendedTimeBetweenSyncs	同期の間隔を示す、推奨最小時間数を表します。この値は、自動同期の場合に、特に優先的に考慮する必要があります。クライアントは、この値を超える頻度で同期を自動的に実行しないでください。ユーザーが開始する同期は、この間隔を超える頻度で実行できます。
MaxBulkDocumentSyncSize	クライアントと同期するコンテンツの合計サイズ。既定値は 500 MB です。GetListItemChangesSinceToken を呼び出すと、各ドキュメントの URL とメタデータを取得しますが、その後で HTTP GET を実行し、実際のドキュメントコンテンツを取得する必要があります。このプロパティを高い値に設定すると、パフォーマンスが低下します。
AlternateUrls	代替 URL は、イントラネットゾーン、既定のゾーン、エクストラネットゾーン、インターネットゾーン、カスタムゾーンの順にコンマ区切りで列挙されます。
EffectiveBasePermissions	SPList.EffectiveBasePermissions.ToString() によって返されるリストに対するアクセス許可。

例

次のコード例では、GetListItemChangesSinceToken メソッドを使用して、現在の変更トークンを表示します。変更トークンは、リストに対する更新が実行されるたびに生成されます。

Dim listService As New Web_Reference_Folder.Lists()
listService.Credentials = System.Net.CredentialCache.DefaultCredentials
listService.Url = "http://MyServer/MyWebSite/_vti_bin/Lists.asmx"

Dim getListName As XmlNode = listService.GetList("MyCalendar")
Dim listName As String = getListName.Attributes("Name").Value

Dim getFirstToken As XmlNode = listService.GetListItemChangesSinceToken(listName, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing)
Dim currentToken As String = getFirstToken.ChildNodes(1).Attributes("LastChangeToken").Value

label1.Text = currentToken + ControlChars.Lf

Dim strEditItemTitle As String = "My New Title"
Dim strBatchEdit As String = "<Batch OnError='Continue'><Method ID='0' Cmd='Update'>" + 
    "<Field Name='Title'>" + strEditItemTitle + "</Field>" + 
    "<Field Name='ID'>2</Field>" + 
    "<Field Name='EventDate'>2007-10-11T14:00:00Z</Field>" + 
    "<Field Name='EndDate'>2007-10-12T14:00:00Z</Field>" + 
    "</Method></Batch>"

Dim doc = New System.Xml.XmlDocument()
doc.LoadXml(strBatchEdit)
Dim editUpdates As XmlNode = doc.DocumentElement

Try
    listService.UpdateListItems(listName, editUpdates)
    Catch ex1 As System.Web.Services.Protocols.SoapException
        MessageBox.Show((ex1.Message + ControlChars.Lf + ex1.Detail.InnerText + ControlChars.Lf + ex1.StackTrace))
End Try

Dim getSecondToken As XmlNode = listService.GetListItemChangesSinceToken(listName, Nothing, Nothing, Nothing, Nothing, Nothing, currentToken, Nothing)

currentToken = getSecondToken.ChildNodes(1).Attributes("LastChangeToken").Value
label1.Text += currentToken + ControlChars.Lf

Dim strNewItemTitle As String = "My New Item"

Dim strBatchNew As String = "<Batch OnError='Continue'><Method ID='0' Cmd='New'>" + 
    "<Field Name='ID'>New</Field>" + 
    "<Field Name='Title'>" + strNewItemTitle + "</Field>" + 
    "<Field Name='EventDate'>2007-10-2T14:00:00Z</Field>" + 
    "<Field Name='EndDate'>2007-10-3T14:00:00Z</Field>" + 
    "</Method></Batch>"

doc = New System.Xml.XmlDocument()
doc.LoadXml(strBatchNew)
Dim addUpdates As XmlNode = doc.DocumentElement

Try
    listService.UpdateListItems(listName, addUpdates)
    Catch ex2 As System.Web.Services.Protocols.SoapException
        MessageBox.Show((ex2.Message + ControlChars.Lf + ex2.Detail.InnerText + ControlChars.Lf + ex2.StackTrace))
End Try

Dim getThirdToken As XmlNode = listService.GetListItemChangesSinceToken(listName, Nothing, Nothing, Nothing, Nothing, Nothing, currentToken, Nothing)

currentToken = getThirdToken.ChildNodes(1).Attributes("LastChangeToken").Value
label1.Text += currentToken

Web_Reference_Folder.Lists listService = new Web_Reference_Folder.Lists();
listService.Credentials = System.Net.CredentialCache.DefaultCredentials;
listService.Url = "http://MyServer/MyWebSite/_vti_bin/Lists.asmx";

XmlNode getListName = listService.GetList("MyCalendar");
string listName = getListName.Attributes["Name"].Value;

XmlNode getFirstToken = listService.GetListItemChangesSinceToken(listName, null, null, null, null, null, null, null);
string currentToken = getFirstToken.ChildNodes[1].Attributes["LastChangeToken"].Value;

label1.Text = currentToken + "\n";

string strEditItemTitle = "My New Title";
string strBatchEdit = "<Batch OnError='Continue'><Method ID='0' Cmd='Update'>" +
    "<Field Name='Title'>" + strEditItemTitle + "</Field>" +
    "<Field Name='ID'>2</Field>" +
    "<Field Name='EventDate'>2007-10-11T14:00:00Z</Field>" +
    "<Field Name='EndDate'>2007-10-12T14:00:00Z</Field>" +
    "</Method></Batch>";

XmlDocument doc = new System.Xml.XmlDocument();
doc.LoadXml(strBatchEdit);
XmlNode editUpdates = doc.DocumentElement;

try
{
    listService.UpdateListItems(listName, editUpdates);
}
catch (System.Web.Services.Protocols.SoapException ex1)
{
    MessageBox.Show(ex1.Message + "\n" + ex1.Detail.InnerText + "\n" + ex1.StackTrace);
}

XmlNode getSecondToken = listService.GetListItemChangesSinceToken(listName, null, null, null, null, null, currentToken, null);

currentToken = getSecondToken.ChildNodes[1].Attributes["LastChangeToken"].Value;
label1.Text += currentToken + "\n";

string strNewItemTitle = "My New Item";

string strBatchNew = "<Batch OnError='Continue'><Method ID='0' Cmd='New'>" +
    "<Field Name='ID'>New</Field>" +
    "<Field Name='Title'>" + strNewItemTitle + "</Field>" +
    "<Field Name='EventDate'>2007-10-2T14:00:00Z</Field>" +
    "<Field Name='EndDate'>2007-10-3T14:00:00Z</Field>" +
    "</Method></Batch>";

doc = new System.Xml.XmlDocument();
doc.LoadXml(strBatchNew);
XmlNode addUpdates = doc.DocumentElement;

try
{
    listService.UpdateListItems(listName, addUpdates);
}
catch (System.Web.Services.Protocols.SoapException ex2)
{
    MessageBox.Show(ex2.Message + "\n" + ex2.Detail.InnerText + "\n" + ex2.StackTrace);
}

XmlNode getThirdToken = listService.GetListItemChangesSinceToken(listName, null, null, null, null, null, currentToken, null);

currentToken = getThirdToken.ChildNodes[1].Attributes["LastChangeToken"].Value;
label1.Text += currentToken;

次の方法で共有

Lists.GetListItemChangesSinceToken メソッド (websvcLists)

構文

パラメータ

戻り値

備考

例

関連項目

参照

その他のリソース