GetListItemChangesSinceToken 请求和响应

上次修改时间： 2015年3月9日

适用范围： SharePoint Foundation 2010

使第三方客户端与 Microsoft SharePoint Foundation 2010 同步的最有效的方法是只下载上次同步后更改的那些项目。可以在 SharePoint Foundation 2010 中通过调用 GetListItemChangesSinceToken Web 方法做到这一点。

GetListItem 从列表返回所有项。GetListItem 不包含任何用于仅获取已更改项目的方法。有关从列表中返回项的示例，请参阅如何：返回列表项。

GetListItemChangesSinceToken 方法允许客户端跟踪列表的更改。更改（包括已删除项目）与表示请求这些更改的时间的令牌一起返回。通过在调用 GetListItemChangesSinceToken 时包括此令牌，服务器会仅查找生成该令牌后发生的那些更改。发送不包含令牌的 GetListItemChangesSinceToken 请求会返回列表架构、完整的列表内容和一个令牌。

备注

如果列表架构本身已更改，则 GetListItemChangesSinceToken 会返回整个列表架构、完整的列表内容和一个令牌。

请求和响应对象

请求和响应对象表示从浏览器进入 Web 服务器的信息和从服务器发出、到达浏览器的信息。请求对象称为输入对象，响应对象称为输出对象。

请求对象

GetListItemChangesSinceToken 使用下列参数：

表 1：请求参数

元素	说明
changeToken（该链接可能指向英文页面）	用于发现上次调用后已更改的令牌。由于此令牌的格式将来可能会更改，因此不应分析或构造此令牌。
contains（该链接可能指向英文页面）	应用于查询结果的 CAML 筛选器。它是 T:Microsoft.SharePoint.SPQuery 中的"Where"子句。备注不要与 query 元素一起使用。
listName（该链接可能指向英文页面）	包含列表的显示名称或列表标识符 (ID) 的字符串，它表示为 GUID。为获得更好的性能，建议使用 GUID，且必须由大括号 ({}) 括起来。
query（该链接可能指向英文页面）	包含确定返回哪些记录以及这些记录的顺序的查询元素。与 GetListItems 和 SPQuery 中使用的 CAML 查询类似的协作应用程序标记语言 (CAML) 查询。有关详细信息，请参阅 SharePoint Foundation SDK 中的 GetListItems 和 SPQuery。备注不适合与 contains 参数一起使用。
queryOptions（该链接可能指向英文页面）	包含 T:Microsoft.SharePoint.SPQuery 对象的各个属性的单独节点的 XML 片段。
rowLimit（该链接可能指向英文页面）	指定在一页上显示的项数或行数的字符串。此参数的值将替代由 viewName 参数指定的视图中设置的行限制或列表的默认视图中设置的行限制。rowLimit 是将返回的值的最大数目。此标记用于分页。
viewFields（该链接可能指向英文页面）	指定查询中返回哪些字段，以及这些字段的顺序。<ViewFields /> 返回列表中的所有字段。Properties=TRUE 属性 (Attribute) 可将 MetaInfo 字段分割为单独的、解码的属性 (Property)。
viewName（该链接可能指向英文页面）	包含视图的 GUID 的字符串，确定由 query、viewFields 和 rowLimit 形参表示的属性的默认视图。如果未提供此实参，则会假定默认视图。如果提供此实参，则 query、viewFields 或 rowLimit 形参的值会替代视图中的等效设置。例如，如果 viewFields 形参指定的视图包含的行限制为 100 行，而 rowLimit 形参包含 1,000，则会在响应时返回 1,000 行。

查询选项参数

queryOptions 元素可能包含大量修改查询的标记。对于 Boolean 选项，默认值为 FALSE。必须输入 TRUE（全部字母大写）值才能启用 Boolean 选项。

下表显示可在通过 queryOptions 参数传递的协作应用程序标记语言 (CAML) 片段中使用的元素。

表 2：可用查询选项标记

元素	说明
< DateInUtc>	以协调世界时 (UTC) 格式和区域返回的数据字段。 UTC 是格林威治时间 (GMT) 的公认名称，以国际标准化组织 (ISO)（通常为 ISO6801）指定的格式表示，如下所示： 2006-10-04T10:00:00Z 标准格式以本地（服务器）时间区域表示（如上所示），但 T 和 Z 由空格替换。
<ExpandUserField>	用户字段值的特殊呈现，可使这些字段值在显示时包括登录名、电子邮件、SipAddress 和标题。这会使用户字段的行为与 multilookup 字段相同。扩展中使用的查阅字段为"Name"、"EMail"、"SipAddress"和"Title"。这些值由 ,# 隔开。查阅字段名称中的所有逗号编码为 ,,。下列值出现在每个项目的常见字段数据中。 <ExpandUserField>FALSE</ExpandUserField> 类似于：ows_Author="1;#Admin AdminName" 和 <ExpandUserField>TRUE</ExpandUserField> 类似于：ows_Author="1;#Admin AdminName,#login\name,#email@address,#sip@address,#Admin AdminName "
<ExtraIds>1,4,23</ExtraIds>	用于包含返回的集中的额外项，无论这些项目是否已发生更改。ExtraId 通常用于指定文件夹的 ID，当您在文档库中并选择"连接到…"，然后选择特定文件夹时，会同步到该文件夹。您通常会获得特定文件夹名称，而不是返回整个文档库。客户端可以检测层次结构中的所有文件夹的删除或重命名时间。备注此标记只应与更改令牌一起使用。除非已对列表完成某些更改，并且获取已更改项目的查询也使用 ID，否则不返回文件夹名称。
<Folder>	设置视图的根文件夹作用域。它是相对于服务器的 URL。 <文件夹>Shared Documents/foldername</文件夹>
<IncludeAttachmentUrls>	将对 Attachments 字段返回的值从 Boolean 值更改为完整的 URL 列表（由 ;# 隔开）
<IncludeAttachmentVersion>	与 IncludeAttachmentUrls 结合使用，此标记返回在验证更新时用于冲突检测的 GUID 和版本号。
<IncludeMandatoryColumns>	确保包括根据需要定义的字段，即使 viewFields 中未指定。此选项可能会令人误解，因为 SharePoint Foundation 确实有一组单独的必填字段，这些必填字段通常以独立于此选项的方式返回。
<IncludePermissions>	客户端可用于请求单个项目权限的一种方法。如果为 TRUE，则请求单个项目权限。
<MeetingInstanceId>	一个整数值，其中的正数表示特定会议实例。负数具有以下含义：-3 = UnSpecified、-2 = AllWithSeries、-1 = AllButSeries、0 = Series。此元素是可选的，其默认值为 -1。负值与 Microsoft.SharePoint.Meetings.SPMeeting.SpecialInstance 枚举的值相对应。
<OptimizeFor>	支持的值包括： ItemIds FolderUrls 只要未请求查询或周期顺序，ItemIds 就为默认值。此标记可使用 ID 顺序优化 SQL Server 查询。 FolderUrls 可优化筛选为一个或多个文件夹的普通内容的同步，方法是使用 DirName、LeafName 顺序优化 SQL Server 查询。 <OptimizeFor>ItemIds</OptimizeFor>
<Paging ListItemCollectionPositionNext="X" />	X 是用于确定要返回的项目的页码的令牌。与 changeToken 值一样，不应分析或构造此令牌。
<RecurrenceOrderBy>	它是一些日历程序的要求。对于每个定期系列，都会先返回主项，然后才返回所有异常。这是在任何其他顺序前应用的特殊内部顺序。备注除非您的程序明确要求此选项，否则不应使用此选项。如果视图包含类型为 Recurrence 的字段，则列表以引用类型唯一标识符 (UID) 的字段为序，并且在周期字段的定义中包括 EventType 和 StartDate。
<RecurrencePatternXMLVersion>	用于维护向后兼容性。RecurrencePatternXMLVersion 可更改 RecurrenceData 字段的值，以便不返回 <V3RecurrencePattern />。包括此标记意味着正确发送了 SharePoint Foundation 新增的定期模式。
<ViewAttributes >	一个字符串，表示在通过 GetView 方法检索视图时，作为 View 元素的一部分返回的所有属性。此元素是可选的，其默认值为空。若要返回库中的所有文档，应按如下方式使用 ViewAttributes 元素：<ViewAttributes Scope="Recursive" />。

默认查询选项

如果未指定 queryOptions 元素，则使用下面的默认选项。

DateInUtc = TRUE
ExpandUserField = TRUE
IncludePermissions = TRUE
IncludeAttachmentUrls = TRUE
IncludeAttachmentVersion = TRUE
MeetingInstanceID = -1
RecurrenceOrderBy = TRUE
RecurrencePatternXMLVersion = v3
ViewAttributes Scope = 'Recursive'

备注

客户端应始终指定一个查询选项；如果未能指定查询选项，则会对性能造成负面影响。

响应对象

在下面的表单中，传递了 XML 格式的 GetListItemChangesSinceToken 响应。此代码段包含所有更改，可分配给 System.Xml.Node 对象。

<listitems 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/">
   <rs:data ItemCount="4">
      <z:row ows_Number_Field="6555.00000000000" 
         ows_Created="2003-06-18T03:41:09Z" 
         ows_ID="3" ows_owshiddenversion="3" />
      <z:row ows_Number_Field="78905456.0000000" 
         ows_Created="2003-06-18T17:15:58Z" 
         ows_ID="4" ows_owshiddenversion="2" />
         ...
   </rs:data>
</listitems>

列表和全局属性

下表介绍返回参数。

表 3：返回参数

参数	定义
AlternateUrls（该链接可能指向英文页面）	备用 URL 按以下区域顺序列出，用逗号分隔：Intranet,Default,Extranet,Internet,Custom
EffectiveBasePermissions（该链接可能指向英文页面）	SPList.EffectiveBasePermissions.ToString() 属性返回的列表权限。
MaxBulkDocumentSyncSize（该链接可能指向英文页面）	必须与客户端同步的内容的总大小（以兆字节 (MB) 计）。默认为 500 MB。调用 GetListItemChangesSinceToken 时会获得每个文档的 URL 和元数据，但这样一来，您必须执行 HTTP GET 才能检索实际文档内容。
MinTimeBetweenSyncs（该链接可能指向英文页面）	一个服务器参数，表示用户启动的同步或自动同步之间的最短时长。该值表示以分钟为单位的时间。备注即使用户启动手动同步，客户端也使用此值。即，如果将此值设置为 5 分钟，即使用户重复单击"发送/接收"，客户端也会每 5 分钟仅发送一次请求。
RecommendedTimeBetweenSyncs（该链接可能指向英文页面）	建议的最小同步时间间隔。不要替代自动同步。客户端的自动同步频率不应超过建议的频率。

更改事件

更改由必须由客户端专门处理的更改事件的列表组成。

提供更改令牌时，会从内部更改日志中获取这些更改事件。对于完全同步（无更改令牌），仍将与当前更改令牌一起返回更改标记。

从更改令牌返回的更新数限制为 100。MoreChanges 属性指示上一个更改令牌并不是最新的。已对列表进行其他更改，并且客户端现在必须使用新的更改令牌再次调用此方法。

表 4：更改事件

更改事件	说明
<Id ChangeType="InvalidToken" />	令牌是旧的或无效。必须执行完全同步。
<Id ChangeType="Restore" />	已从回收站或备份还原列表。您应执行完全同步。
<List></List>	如果列表架构已更改，或未提供更改令牌，则会返回完整列表。格式与 GetList 返回的格式相同。

在上述两种情况下，客户端应忽略其他更改，并对列表执行完全调整。

表 5：更改类型

更改类型	说明
<Id ChangeType="Delete">ID</Id>	此项目不再存在。请注意，即使项目是由查询筛选出来的，也会发送 delete 更改。
<Id ChangeType="MoveAway" AfterListId="ID" AfterItemId="ID">ID</Id>	这些项目的处理方式与删除更改项目相同，这意味着即使项目是由查询筛选出来的，也会返回这些项目。
<Id ChangeType="Restore">ID</Id>	已还原此项目和此项目下的所有项目。
<Id ChangeType="SystemUpdate">ID</Id>	一些客户端可能使用隐藏版本、版本历史记录或修改时间来确定是否更新某项。SystemUpdate 意味着 Windows SharePoint Services 3.0 已进行更改，并且您需要更新该特定项上的所有属性。
<Id ChangeType="Rename">ID</Id>	重命名的项目（如 SystemUpdate）可能保留隐藏版本信息。

数据

ItemCount 属性包含返回的项数。每个项目返回为一个 <z:row> 标记。

仅当 rowLimit 参数已用于限制在一个调用中返回的项数时，才会对完全同步（无更改令牌）返回 ListItemCollectionPositionNext 属性。对于增量同步，会通过将从更改日志处理的更新数限制为行限制（如果该数目小于内部最大限制）阻止此类型的分页。

这些项目的内容返回为带"ows_"前缀和字段的内部名称的属性。这些值会编码为有效的 XML 属性值。始终返回一组字段。

如果设置 IncludeMandatoryColumns 选项，则一些字段会标记为必填并返回这些字段。如果发送 <ViewFields />，则会返回所有字段。

当在 ViewFields 标记中设置了 Properties="TRUE" 时，会将属性 (Property) 包（MetaInfo 字段）分割为每个属性 (Property) 一个属性 (Attribute)。这些属性 (Attribute) 的前缀为"ows_MetaInfo_"。

多数栏值是从其内部表示形式转换而来，但其他栏值是专门为客户端构造的。列表架构中的若干属性未由字段表示。

表 6：列表架构中未由字段表示的属性

属性	说明
MetaInfo	属性包容器 SPListItem.Properties。有关详细信息，请参阅 SPListItem 对象模型中的属性包。
类型为"Attachments"的字段	数据库中可由查询选项修改以返回附件数据的位栏。
RecurrenceData	周期的 XML 定义。有关此 XML 架构的详细信息，请参阅 https://blogs.msdn.com/b/sharepoint/archive/2007/05/14/understanding-the-sharepoint-calendar-and-how-to-export-it-to-ical-format.aspx（该链接可能指向英文页面）。

MetaInfo

属性包容器 SPListItem.Properties。有关详细信息，请参阅 SPListItem 对象模型中的属性包。

类型为"Attachments"的字段

数据库中可由查询选项修改以返回附件数据的位栏。

RecurrenceData

周期的 XML 定义。

有关此 XML 架构的详细信息，请参阅 https://blogs.msdn.com/b/sharepoint/archive/2007/05/14/understanding-the-sharepoint-calendar-and-how-to-export-it-to-ical-format.aspx（该链接可能指向英文页面）。

请参阅

概念

GetListItemChangesSinceToken 和同步应用程序

如何：更新列表项

Last updated on 2015-06-15

通过