GetListItemChangesSinceToken - Anforderung und Antwort

Artikel
09/24/2014

Letzte Änderung: Montag, 1. November 2010

Gilt für: SharePoint Foundation 2010

Die effizienteste Methode zum Synchronisieren von Clients von Drittanbietern mit Microsoft SharePoint Foundation 2010 besteht darin, nur die Elemente herunterzuladen, die seit der letzten Synchronisierung geändert wurden. In SharePoint Foundation 2010 erreichen Sie dies durch den Aufruf der GetListItemChangesSinceToken-Webmethode.

GetListItem gibt alle Elemente aus einer Liste zurück. GetListItem enthält keine Methode, um nur die geänderten Elemente abzurufen. Ein Beispiel für die Rückgabe von Elementen aus einer Liste finden Sie unter Gewusst wie: Zurückgeben von Listenelementen.

Die GetListItemChangesSinceToken-Methode ermöglicht Clients die Nachverfolgung von Änderungen in einer Liste. Änderungen, einschließlich gelöschter Elemente, werden zusammen mit einem Token zurückgegeben, das den Zeitpunkt darstellt, zu dem die Änderungen angefordert wurden. Wird dieses Token beim Aufruf von GetListItemChangesSinceToken angegeben, werden vom Server nur die Änderungen gesucht, die seit der Generierung des Tokens vorgenommen wurden. Beim Senden einer GetListItemChangesSinceToken-Anforderung ohne ein Token werden das Listenschema, der vollständige Listeninhalt und ein Token zurückgegeben.

Hinweis
Wenn das Listenschema selbst geändert wurde, gibt GetListItemChangesSinceToken das gesamte Listenschema, den vollständigen Listeninhalt und ein Token zurück.

Anforderungs- und Antwortobjekte

Anforderungs- und Antwortobjekte stellen auf dem Webserver vom Browser eingehende Informationen und vom Server ausgehende Informationen an den Browser dar. Das Anforderungsobjekt wird als Eingabeobjekt und das Antwortobjekt als Ausgabeobjekt bezeichnet.

Anforderungsobjekte

GetListItemChangesSinceToken akzeptiert die folgenden Parameter:

Tabelle 1: Anforderungsparameter

Element	Beschreibung
changeToken	Ein Token, das zur Erkennung von Änderungen verwendet wird, die seit dem letzten Aufruf aufgetreten sind. Dieses Token sollte weder analysiert noch neu erstellt werden, da sich das Format in Zukunft ändern kann.
contains	Ein CAML-Filter, der auf die Abfrageergebnisse angewendet wird. Dies ist die "Where"-Klausel in einer T:Microsoft.SharePoint.SPQuery-Abfrage. Hinweis Verwenden Sie den Parameter nicht zusammen mit dem query-Element.
listName	Eine Zeichenfolge, die entweder den Anzeigenamen der Liste oder den Listenbezeichner (ID) enthält, der als GUID angegeben wird. Aus Leistungsgründen empfiehlt sich die Verwendung der GUID, die in geschweifte Klammern ({}) eingeschlossen werden muss.
query	Ein Abfrageelement, das die Abfrage enthält, die bestimmt, welche Datensätze in welcher Reihenfolge zurückgegeben werden. Eine CAML-Abfrage (Collaborative Application Markup Language) ähnlich der in GetListItems und SPQuery verwendeten CAML-Abfrage. Weitere Informationen finden Sie unter "GetListItems" und "SPQuery" im SharePoint Foundation SDK. Hinweis Nicht für die Verwendung mit dem contains-Parameter vorgesehen.
queryOptions	Ein XML-Fragment, das separate Knoten für die verschiedenen Eigenschaften des T:Microsoft.SharePoint.SPQuery-Objekts enthält.
rowLimit	Eine Zeichenfolge, die die Anzahl der pro Seite anzuzeigenden Elemente oder Zeilen angibt. Der Wert dieses Parameters überschreibt die in der Ansicht festgelegte Zeilenbeschränkung, die durch den viewName-Parameter angegeben wurde, oder die in der Standardansicht für die Liste festgelegte Zeilenbeschränkung. rowLimit gibt die maximale Anzahl von zurückzugebenden Werten an. Dieses Tag wird für die Seitenverwaltung verwendet.
viewFields	Gibt an, welche Felder in welcher Reihenfolge in der Abfrage zurückgegeben werden. <ViewFields /> gibt alle Felder in der Liste zurück. Durch ein Attribut Properties=TRUE wird das MetaInfo-Feld in seine einzelnen, decodierten Eigenschaften aufgeteilt.
viewName	Eine Zeichenfolge, die die GUID der Ansicht enthält, die die Standardansicht für Attribute bestimmt, die durch die Parameter query, viewFields und rowLimit dargestellt werden. Wenn dieses Argument nicht angegeben wird, wird die Standardansicht verwendet. Wenn es angegeben wird, überschreibt der Wert der Parameter query, viewFields oder owLimit die entsprechende Einstellung in der Ansicht. Gilt beispielsweise für die durch den viewFields-Parameter angegebene Ansicht eine Zeilenbeschränkung von 100 Zeilen, aber der rowLimit-Parameter enthält den Wert 1.000, werden 1.000 Zeilen in der Antwort zurückgegeben.

Abfrageoptionsparameter

Das queryOptions-Element kann eine Vielzahl von Tags zur näheren Bestimmung der Abfrage enthalten. Der Standardwert für boolesche Optionen lautet FALSE. Sie müssen den Wert TRUE (in Großbuchstaben) eingeben, um eine Boolean-Option zu aktivieren.

Die folgende Tabelle enthält die Elemente, die in dem CAML-Fragment (Collaborative Application Markup Language) verwendet werden können, das durch den queryOptions-Parameter übergeben wird.

Tabelle 2: Verfügbare Tags für Abfrageoptionen

Element	Beschreibung
< DateInUtc>	Datumsfelder werden im UTC-Format (Coordinated Universal Time) und der entsprechenden Zeitzone zurückgegeben. UTC ist der international anerkannte Name für Greenwich Mean Time (GMT) und wird in einem Format dargestellt, das von der International Organization for Standardization (ISO), insbesondere in ISO6801, wie folgt festgelegt wurde: 2006-10-04T10:00:00Z Das Standardformat wird in der lokalen Zeitzone (des Servers) ausgedrückt, wie oben dargestellt, wobei jedoch die Buchstaben "T" und "Z" durch Leerzeichen ersetzt werden.
<ExpandUserField>	Spezielles Rendering für die Benutzerfeldwerte, wobei der Benutzername, die E-Mail-Adresse, die SIP-Adresse und ggf. der Titel eingeschlossen werden. Dadurch verhält sich ein Benutzerfeld wie ein Feld mit Mehrfachsuchoption. Die in der Erweiterung verwendeten Nachschlagefelder sind "Name", "EMail", "SipAddress" und "Title". Die Werte werden durch ,# getrennt. Alle Kommas im Namen des Nachschlagefelds werden als ,, codiert. Die folgenden Werte treten in den normalen Felddaten für jedes Element auf. <ExpandUserField>FALSE</ExpandUserField> sieht aus wie: ows_Author="1;#Admin AdminName" und <ExpandUserField>TRUE</ExpandUserField> sieht aus wie: ows_Author="1;#Admin AdminName,#login\name,#email@address,#sip@address,#Admin AdminName "
<ExtraIds>1,4,23</ExtraIds>	Dient zum Einschließen zusätzlicher Elemente in die zurückgegebene Menge, unabhängig davon, ob sie geändert wurden. Häufig werden mit ExtraIds die IDs der Ordner angegeben, mit denen Sie synchronisieren, wenn Sie in einer Dokumentbibliothek "Verbinden mit" und dann einen bestimmten Ordner auswählen. Statt die gesamte Dokumentbibliothek zurückzugeben, erhalten Sie den spezifischen Ordnernamen. Der Client kann erkennen, wenn ein Ordner in der Hierarchie gelöscht oder umbenannt wurde. Ordnernamen werden nur zurückgegeben, wenn Änderungen an der Liste vorgenommen wurden und in der Abfrage zum Abrufen geänderter Elemente ebenfalls IDs verwendet werden.
<Folder>	Legt den Stammordnerbereich der Ansicht fest. Dabei handelt es sich um eine serverrelative URL. <Folder>Shared Documents/foldername</Folder>
<IncludeAttachmentUrls>	Ändert den Wert, der für das Attachments-Feld zurückgegeben wird, von einem booleschen Wert in eine Liste von vollständigen, durch ;# getrennten URLs.
<IncludeAttachmentVersion>	Wird in Verbindung mit IncludeAttachmentUrls verwendet und gibt die GUID und die Versionsnummer für die Konflikterkennung bei der Überprüfung eines Updates zurück.
<IncludeMandatoryColumns>	Stellt sicher, dass als erforderlich definierte Felder eingeschlossen werden, auch wenn sie nicht in viewFields angegeben sind. Diese Option ist möglicherweise irreführend, da SharePoint Foundation tatsächlich über einen Satz von Pflichtfeldern verfügt, die unabhängig von dieser Option immer zurückgegeben werden.
<IncludePermissions>	Eine Methode, mit der ein Client einzelne Elementberechtigungen anfordern kann. TRUE zum Anfordern von Berechtigungen für einzelne Elemente.
<MeetingInstanceId>	Ein ganzzahliger Wert, wobei eine positive Zahl eine bestimmte Besprechungsinstanz darstellt. Negative Zahlen haben folgende Bedeutung: -3 = UnSpecified, -2 = AllWithSeries, -1 = AllButSeries, 0 = Series. Dieses Element ist optional, und der Standardwert ist -1. Negative Werte entsprechen Werten der Microsoft.SharePoint.Meetings.SPMeeting.SpecialInstance-Enumeration.
<OptimizeFor>	Unterstützte Werte: ItemIds FolderUrls ItemIds ist der Standardwert, wenn keine Abfrage- oder Serienreihenfolge gefordert wird. Dieses Tag optimiert die SQL Server-Abfrage mit einer ID-Reihenfolge. FolderUrls optimiert eine Synchronisierung, die zum flachen Inhalt eines oder mehrerer Ordner gefiltert wird, durch Optimieren der SQL Server-Abfrage mit der Reihenfolge DirName, LeafName. <OptimizeFor>ItemIds</OptimizeFor>
<Paging ListItemCollectionPositionNext="X" />	X ist ein Token, das verwendet wird, um die Seite von zurückzugebenden Elementen zu bestimmen. Wie der changeToken-Wert sollte dieses Token nie analysiert oder erstellt werden.
<RecurrenceOrderBy>	Dies ist eine Anforderung einiger Kalenderprogramme. Für jede Serie wird zuerst das Masterelement und dann alle Ausnahmen zurückgegeben. Hierbei handelt es sich um eine spezielle interne Reihenfolge, die vor jeder anderen Sortierung angewendet wird. Wenn die Ansicht ein Feld vom Typ Recurrence enthält, wird die Liste nach Feldern mit Verweistyp-UIDs (Unique Identifiers) sortiert und enthält EventType und StartDate in der Definition des Serienfelds.
<RecurrencePatternXMLVersion>	Dient zur Aufrechterhaltung der Abwärtskompatibilität. RecurrencePatternXMLVersionändert den Wert eines RecurrenceData-Felds, sodass <V3RecurrencePattern /> nicht zurückgegeben wird. Bei Einschließen dieses Tags werden in SharePoint Foundation neue Serienmuster ordnungsgemäß gesendet.
<ViewAttributes >	Eine Zeichenfolge, die alle als Teil des View-Elements zurückgegebenen Attribute darstellt, wenn eine Ansicht über die GetView-Methode abgerufen wird. Dieses Element ist optional, und der Standardwert ist leer. Zum Zurückgeben aller Dokumente in einer Bibliothek wird das ViewAttributes-Element wie folgt verwendet: <ViewAttributes Scope="Recursive" />.

Standardabfrageoptionen

Wenn das queryOptions-Element nicht angegeben wird, werden die folgenden Standardoptionen verwendet.

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

Hinweis

Von Clients sollte immer eine Abfrageoption angegeben werden. Andernfalls wird die Skalierungsleistung beeinträchtigt.

Hinweis
Von Clients sollte immer eine Abfrageoption angegeben werden. Andernfalls wird die Skalierungsleistung beeinträchtigt.

Antwortobjekte

Eine GetListItemChangesSinceToken-Antwort wird in einem XML-Format ähnlich dem folgenden übermittelt. Dieses Fragment enthält alle Änderungen und kann einem System.Xml.Node-Objekt zugewiesen werden.

<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>

Listen- und globale Eigenschaften

In der folgenden Tabelle sind die Rückgabeparameter beschrieben.

Tabelle 3: Rückgabeparameter

Parameter	Beschreibung
AlternateUrls	Alternative URLs werden in der folgenden Zonenreihenfolge, durch Kommas getrennt, aufgeführt: Intranet, Standard, Extranet, Internet, Benutzerdefiniert
EffectiveBasePermissions	Die Berechtigungen für die Liste, die von der SPList.EffectiveBasePermissions.ToString()-Eigenschaft zurückgegeben wird.
MaxBulkDocumentSyncSize	Die Gesamtgröße der Inhalte, in Megabyte (MB), die mit dem Client synchronisiert werden müssen. Der Standardwert beträgt 500 MB. Sie erhalten die URL und die Metadaten für jedes Dokument durch den Aufruf von GetListItemChangesSinceToken, anschließend müssen Sie jedoch eine HTTP GET-Anforderung zum Abrufen der tatsächlichen Dokumentinhalte ausführen.
MinTimeBetweenSyncs	Ein Serverparameter, der die minimale Zeitspanne zwischen benutzerinitiierten oder automatischen Synchronisierungsvorgängen darstellt. Der Wert gibt einen Zeitraum in Minuten an. Hinweis Von Clients wird dieser Wert auch verwendet, wenn der Benutzer eine manuelle Synchronisierung initiiert. Wenn der Wert beispielsweise auf 5 Minuten festgelegt ist, senden Clients somit nur alle 5 Minuten eine Anforderung, auch wenn der Benutzer wiederholt auf "Senden/Empfangen" klickt.
RecommendedTimeBetweenSyncs	Die empfohlene minimale Zeitspanne zwischen Synchronisierungen. Überschreiben Sie den Wert nicht für automatische Synchronisierungen. Clients sollten nicht häufiger als empfohlen eine automatische Synchronisierung ausführen.

Änderungsereignisse

Änderungen bestehen aus einer Liste von Änderungsereignissen, die spezifisch vom Client verarbeitet werden müssen.

Diese Änderungsereignisse werden dem internen Änderungsprotokoll entnommen, wenn ein Änderungstoken bereitgestellt wird. Für eine vollständige Synchronisierung (kein Änderungstoken) wird das Änderungstag weiterhin mit dem aktuellen Änderungstoken zurückgegeben.

Der Grenzwert für die Anzahl der Updates, die von einem Änderungstoken zurückgegeben werden, ist 100. Das MoreChanges-Attribut gibt an, dass das letzte Änderungstoken nicht aktuell ist. Weitere Änderungen wurden an der Liste vorgenommen, und der Client muss nun diese Methode erneut mit dem neuen Änderungstoken aufrufen.

Tabelle 4: Änderungsereignisse

Änderungsereignisse	Beschreibung
<Id ChangeType="InvalidToken" />	Das Token ist entweder ungültig oder alt. Sie müssen eine vollständige Synchronisierung ausführen.
<Id ChangeType="Restore" />	Die Liste wurde aus dem Papierkorb oder aus einer Sicherung wiederhergestellt. Sie sollten eine vollständige Synchronisierung ausführen.
<List></List>	Wenn das Listenschema geändert wurde oder kein Änderungstoken bereitgestellt wurde, wird die vollständige Liste zurückgegeben. Das Format entspricht dem von GetList zurückgegebenen.

In den ersten beiden oben genannten Fällen sollte der Client weitere Änderungen ignorieren und eine vollständige Abstimmung der Liste ausführen.

Tabelle 5: Änderungstypen

Änderungstyp	Beschreibung
<Id ChangeType="Delete">ID</Id>	Dieses Element ist nicht mehr vorhanden. Beachten Sie, dass delete-Änderungen auch gesendet werden, wenn das Element von der Abfrage herausgefiltert wurde.
<Id ChangeType="MoveAway" AfterListId="ID" AfterItemId="ID">ID</Id>	Diese Elemente werden auf die gleiche Weise wie ein Änderungselement zur Löschung behandelt. Das heißt, dass sie auch zurückgegeben werden, wenn das Element von der Abfrage herausgefiltert wurde.
<Id ChangeType="Restore">ID</Id>	Dieses Element und alle untergeordneten Elemente wurden wiederhergestellt.
<Id ChangeType="SystemUpdate">ID</Id>	Von einigen Clients werden möglicherweise die ausgeblendete Version, der Versionsverlauf oder die Änderungszeit verwendet, um zu bestimmen, ob ein Element aktualisiert werden muss. SystemUpdate bedeutet, dass von Windows SharePoint Services 3.0 Änderungen vorgenommen wurden und dass Sie alle Eigenschaften für dieses bestimmte Element aktualisieren müssen.
<Id ChangeType="Rename">ID</Id>	Für umbenannte Elemente, wie z. B. SystemUpdate, bleiben möglicherweise ausgeblendete Versionsinformationen erhalten.

Daten

Das ItemCount-Attribut enthält die Anzahl der zurückgegebenen Elemente. Jedes Element wird als ein <z:row>-Tag zurückgegeben.

Ein ListItemCollectionPositionNext-Attribut wird nur dann für eine vollständige Synchronisierung (kein Änderungstoken) zurückgegeben, wenn die Anzahl der in einem Aufruf zurückgegebenen Elemente mit einem rowLimit-Parameter beschränkt wurde. Diese Art der Seitenverwaltung wird bei einer inkrementellen Synchronisierung unterbunden, indem die Zahl der verarbeiteten Updates aus dem Änderungsprotokoll auf die maximale Zeilenanzahl beschränkt wird, wenn diese Zahl kleiner als der interne Maximalwert ist.

Die Inhalte der Elemente werden als Attribute mit dem Präfix "ows_" und dem internen Namen des Felds zurückgegeben. Die Werte werden als gültige XML-Attributwerte codiert. Ein Satz von Feldern wird immer zurückgegeben.

Einige Felder sind als erforderlich gekennzeichnet und werden zurückgegeben, wenn die IncludeMandatoryColumns-Option angegeben wurde. Wenn <ViewFields /> gesendet wird, werden alle Felder zurückgegeben.

Wenn im ViewFields-Tag Properties="TRUE" festgelegt wurde, wird der Eigenschaftenbehälter (das MetaInfo-Feld) in ein Attribut pro Eigenschaft unterteilt. Diese Attribute weisen das Präfix "ows_MetaInfo_" auf.

Die meisten Spaltenwerte werden einfach aus der internen Darstellung konvertiert, während andere speziell für einen Client erstellt werden. Mehrere Attribute im Listenschema werden nicht von einem Feld dargestellt.

Tabelle 6: Attribute, die nicht durch ein Feld im Listenschema dargestellt werden

Attribut	Beschreibung
MetaInfo	Eigenschaftenbehälter, SPListItem.Properties. Weitere Informationen finden Sie unter dem Eigenschaftenbehälter im SPListItem-Objektmodell.
Felder vom Typ "Attachments"	Eine Bit-Spalte in der Datenbank, die durch Abfrageoptionen für die Rückgabe von Anlagendaten geändert werden kann.
RecurrenceData	Die XML-Definition einer Serie. Weiter Informationen zu diesem XML-Schema finden Sie unter https://blogs.msdn.com/sharepoint/archive/2007/05/14/understanding-the-sharepoint-calendar-and-how-to-export-it-to-ical-format.aspx.

MetaInfo

Eigenschaftenbehälter, SPListItem.Properties. Weitere Informationen finden Sie unter dem Eigenschaftenbehälter im SPListItem-Objektmodell.

Felder vom Typ "Attachments"

Eine Bit-Spalte in der Datenbank, die durch Abfrageoptionen für die Rückgabe von Anlagendaten geändert werden kann.

RecurrenceData

Die XML-Definition einer Serie.

Weiter Informationen zu diesem XML-Schema finden Sie unter https://blogs.msdn.com/sharepoint/archive/2007/05/14/understanding-the-sharepoint-calendar-and-how-to-export-it-to-ical-format.aspx.

Siehe auch

Konzepte

GetListItemChangesSinceToken und Synchronisieren von Anwendungen

Gewusst wie: Aktualisieren von Listenelementen

Freigeben über