Demande (Request) et réponse (Response) GetListItemChangesSinceToken

Article
09/24/2014

Dernière modification : lundi 1 novembre 2010

S’applique à : SharePoint Foundation 2010

Pour synchroniser des clients tiers avec Microsoft SharePoint Foundation 2010 la méthode la plus efficace consiste à télécharger uniquement les éléments qui ont changé que depuis que la dernière synchronisation s’est produite. Pour cela SharePoint Foundation 2010, appelez la méthode Web GetListItemChangesSinceToken.

GetListItem retourne tous les éléments à partir d'une liste. GetListItem ne comprend aucune méthode permettant d'obtenir uniquement les éléments qui ont été modifiés. Consultez l'article Procédure : retourner des éléments de liste pour obtenir un exemple de renvoi d'éléments à partir d'une liste.

La méthode GetListItemChangesSinceToken permet aux clients d'effectuer un suivi des modifications sur une liste. Les modifications, notamment les éléments supprimés, sont retournées avec un jeton qui représente le moment où ces modifications ont été demandées. En incluant ce jeton lorsque vous appelez GetListItemChangesSinceToken, le serveur recherche uniquement les modifications ayant eu lieu depuis que le jeton a été généré. L'envoi d'une demande GetListItemChangesSinceToken sans y inclure un jeton retourne le schéma de liste, le contenu de la liste complète et un jeton.

Notes

Si le schéma de liste lui-même a changé, GetListItemChangesSinceToken retourne le schéma de liste entier, le contenu de la liste complète et un jeton.

Objets de demande (Request) et de réponse (Response)

Les objets de demande (Request) et de réponse (Response) représentent des informations parvenant au serveur Web depuis le navigateur et des informations allant du serveur au navigateur. L'objet de demande est appelé objet d'entrée et l'objet de réponse est appelé objet de sortie.

Objets de demande (Request)

GetListItemChangesSinceToken accepte les paramètres suivants :

Tableau 1 : paramètres de demande

Élément	Description
changeToken (éventuellement en anglais)	Jeton utilisé pour découvrir les modifications qui se sont produites depuis le dernier appel. Ce jeton ne doit jamais être analysé ou construit, car son format peut changer à l'avenir.
contains (éventuellement en anglais)	Filtre CAML qui est appliqué aux résultats de la requête. Il s’agit de la clause « WHERE » dans un T:Microsoft.SharePoint.SPQuery Remarque À ne pas utiliser avec l'élément Requête de service Web.
listName (éventuellement en anglais)	Chaîne qui contient le nom complet de la liste ou l'identificateur de liste (ID), qui est exprimé sous forme de GUID. Pour obtenir de meilleures performances, nous conseillons d'utiliser le GUID, qui doit être entouré d'accolades ({}).
query (éventuellement en anglais)	Élément de requête contenant la requête qui détermine quels enregistrements sont retournés et dans quel ordre. La requête CAML (Collaborative Application Markup Language) est similaire à la requête CAML utilisée dans GetListItems et SPQuery. Pour plus d’informations, voir GetListItems et SPQuery dans le Kit de développement logiciel (SDK) SharePoint Foundation. Remarque Pas prévu pour être utilisé avec le paramètre contains.
queryOptions (éventuellement en anglais)	Fragment XML qui contient des nœuds distincts pour les différentes propriétés de l’objet T:Microsoft.SharePoint.SPQuery.
rowLimit (éventuellement en anglais)	Chaîne qui spécifie le nombre d'éléments, ou de lignes, à afficher sur une page. La valeur de ce paramètre remplace la limite de lignes définie dans la vue spécifiée par le paramètre viewName, ou la limite de lignes définie dans la vue par défaut de la liste. rowLimit est le nombre maximal de valeurs qui seront retournées. Cette balise est utilisée pour la pagination.
viewFields (éventuellement en anglais)	Spécifie les champs à retourner dans la requête et dans quel ordre. <ViewFields /> Retourne tous les champs dans la liste. Un attribut Properties=TRUE sépare le champ MetaInfo en ses propriétés distinctes, déchiffrées.
viewName (éventuellement en anglais)	Chaîne contenant le GUID pour l'affichage, qui détermine la vue par défaut pour les attributs qui sont représentés par les paramètres query, viewFields et rowLimit. Si cet argument n'est pas fourni, la vue par défaut est supposée. S'il est fourni, la valeur des paramètres query, viewFields et owLimit remplace la valeur équivalente dans la vue. Par exemple, si la vue spécifiée par le paramètre viewFields a une limite de 100 lignes mais que le paramètre rowLimit en contient 1 000, alors 1 000 lignes sont retournées dans la réponse.

Paramètre d'options de requête

L'élément queryOptions peut contenir plusieurs balises qui modifient la requête. Pour les options booléennes, la valeur par défaut est FALSE. Vous devez entrer une valeur TRUE (en majuscules) pour activer une option Boolean.

Le tableau suivant montre les éléments qui peuvent être utilisés dans le fragment CAML (Collaborative Application Markup Language) transmis via le paramètre queryOptions.

Tableau 2 : balises d'options de requête disponibles

Élément	Description
< DateInUtc>	Les champs de date sont retournés dans les format et zone UTC (Temps universel coordonné). UTC est le nom mondialement reconnu de l'heure de Greenwich (GMT) et est exprimé en un format spécifié par l'Organisation internationale de normalisation (ISO), spécifiquement ISO6801, comme suit : 2006-10-04T10:00:00Z Le format standard est exprimé dans le fuseau horaire local (serveur), comme indiqué ci-dessus, mais avec les lettres T et Z remplacées par des espaces.
<ExpandUserField>	Affichage spécial des valeurs de champs utilisateur qui permet d'y inclure le nom d'ouverture de session, l'adresse de messagerie, l'adresse SIP (SipAddress) et le titre, le cas échéant. Cela fait qu'un champ d'utilisateur se comporte comme un champ multirecherche. Les champs de recherche utilisés dans l'expansion sont « Name », « EMail », « SipAddress » et « Title ». Les valeurs sont séparées par ,#. Les virgules dans le nom du champ de recherche sont chiffrées en ,,. Les valeurs suivantes surviennent dans les données du champ normal pour chaque élément. <ExpandUserField>FALSE</ExpandUserField> ressemble à ceci : ows_Author="1;#Admin AdminName" et <ExpandUserField>TRUE</ExpandUserField> ressemble à ceci : ows_Author="1;#Admin AdminName,#login\name,#email@address,#sip@address,#Admin AdminName"
<ExtraIds>1,4,23</ExtraIds>	Utilisés pour inclure des éléments supplémentaires dans le jeu retourné, qu'ils aient changé ou non. Les ExtraIds sont couramment utilisés pour spécifier les ID des dossiers que vous synchronisez lorsque vous vous trouvez dans une bibliothèque de documents et choisissez « se connecter à… », puis sélectionnez un dossier particulier. Au lieu de retourner la bibliothèque de documents entière, vous obtenez le nom de dossier spécifique. Le client peut détecter quand un dossier de l'arborescence a été supprimé ou renommé. Les noms de dossiers ne sont retournés que si certaines modifications apportées à la liste ont été effectuées et la requête pour extraire des éléments modifiés utilise également des ID.
<Folder>	Définit l'étendue du dossier racine de la vue. Il s'agit d'une URL relative de serveur. <Folder>Shared Documents/foldername</Folder>
<IncludeAttachmentUrls>	Modifie la valeur qui est retournée pour le champ Pièces jointes d'une valeur booléenne vers une liste d'URL complètes, séparées par ;#
<IncludeAttachmentVersion>	Utilisée conjointement avec IncludeAttachmentUrls, cette balise renvoie le numéro et la version de GUID utilisés pour la détection des conflits lorsqu'une mise à jour est vérifiée.
<IncludeMandatoryColumns>	Permet de s’assurer que les champs définis comme étant requis sont inclus, même si cela n’est pas spécifié dans viewFields. Cette option peut être trompeuse, car SharePoint Foundation a en réalité un ensemble distinct de champs obligatoires qui sont toujours retournés indépendamment de cette option.
<IncludePermissions>	Une méthode qu'un client peut utiliser pour demander des autorisations d'élément individuelles. TRUE pour demander des autorisations d'élément individuelles.
<MeetingInstanceId>	Valeur entière où un nombre positif représente une instance de réunion spécifique. Les valeurs négatives ont les significations suivantes : -3 = UnSpecified, -2 = AllWithSeries, -1 = AllButSeries, 0 = Series. Cet élément est facultatif, et sa valeur par défaut est -1. Les valeurs négatives correspondent aux valeurs de l'énumération Microsoft.SharePoint.Meetings.SPMeeting.SpecialInstance.
<OptimizeFor>	Les valeurs prises en charge incluent : ItemIds FolderUrls ItemIds est la valeur par défaut tant qu'un ordre de requête ou de périodicité n'est pas demandé. Cette balise permet d'optimiser votre requête SQL Server avec un ordre d'ID. FolderUrls optimise une synchronisation qui est filtrée pour le contenu à deux dimensions d'un ou plusieurs dossiers, en optimisant la requête SQL Server avec un ordre DirName, LeafName. <OptimizeFor>ItemIds</OptimizeFor>
<Paging ListItemCollectionPositionNext=”X” />	X est un jeton qui est utilisé pour déterminer la page d'éléments à retourner. Tout comme la valeur changeToken, ce jeton ne doit jamais être analysé ou construit.
<RecurrenceOrderBy>	Il s'agit d'une exigence pour certains programmes de calendrier. Pour chaque série périodique, l'élément principal est retourné en premier, avant toutes les exceptions. Il s'agit d'un classement spécial interne qui est appliqué avant tout autre classement. Si la vue a un champ de type Recurrence, la liste est classée en champs d'identificateurs uniques (UID) de type référence et inclut EventType et StartDate dans la définition du champ de périodicité.
<RecurrencePatternXMLVersion>	Utilisée pour conserver une compatibilité descendante. RecurrencePatternXMLVersion modifie la valeur d’un champ RecurrenceData pour ne pas retourner <V3RecurrencePattern />. L’inclusion de cette balise signifie que des modèles de périodicité nouveaux pour SharePoint Foundation sont envoyés correctement.
<ViewAttributes >	Chaîne qui représente tous les attributs retournés dans le cadre de l'élément View lors de l'extraction d'une vue via la méthode GetView. Cet élément est facultatif, et sa valeur par défaut est vide. Pour renvoyer tous les documents dans une bibliothèque, l'élément ViewAttributes est utilisé comme suit : <ViewAttributes Scope=”Recursive” />.

Options de requête par défaut

Si l'élément queryOptions n'est pas spécifié, les options par défaut suivantes sont utilisées.

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

Notes

Les clients doivent toujours spécifier une option de requête ; sinon, cela peut avoir un impact négatif sur les performances d'échelle.

Objets de réponse

Une réponse GetListItemChangesSinceToken est remise au format XML dans le formulaire illustré ci-dessous. Ce fragment contient toutes les modifications et peut être affecté à un objet 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>

Liste et propriétés globales

Le tableau suivant décrit les paramètres de retour.

Tableau 3 : paramètres de retour

Paramètre	Définition
AlternateUrls (éventuellement en anglais)	Les URL de remplacement sont répertoriées dans l'ordre des zones suivantes, séparées par des virgules : Intranet,Default,Extranet,Internet,Custom
EffectiveBasePermissions (éventuellement en anglais)	Les autorisations dans la liste qui est retournée par la propriété SPList.EffectiveBasePermissions.ToString().
MaxBulkDocumentSyncSize (éventuellement en anglais)	La taille totale du contenu, en mégaoctets (Mo), qui doit être synchronisé avec le client. La valeur par défaut est de 500 Mo. Vous obtenez les URL et les métadonnées pour chaque document lorsque vous appelez GetListItemChangesSinceToken, mais vous devez ensuite effectuer une demande HTTP GET pour récupérer le contenu du document réel.
MinTimeBetweenSyncs (éventuellement en anglais)	Un paramètre du serveur qui représente la durée minimale entre la synchronisation initiée par l'utilisateur et la synchronisation automatique. La valeur représente une durée en minutes. Remarque Les clients utilisent cette valeur, même si l'utilisateur lance une synchronisation manuelle. C'est-à-dire, si cette valeur est définie à 5 minutes, les clients n'envoient qu'une seule requête toutes les 5 minutes, même si l'utilisateur clique à plusieurs reprises sur « Envoyer/Recevoir ».
RecommendedTimeBetweenSyncs (éventuellement en anglais)	La durée minimale recommandée entre les synchronisations. Ne substituez pas pour les synchronisations automatiques. Les clients ne doivent jamais synchroniser automatiquement plus souvent que ce qui est recommandé.

Événements de modification

Les modifications se composent d'une liste d'événements de modification qui doit être gérée spécifiquement par le client.

Ces événements de modification proviennent du journal des modifications interne lorsqu'un jeton de modification est fourni. Pour une synchronisation complète (pas de jeton de modification), la balise des modifications est toujours retournée par le jeton de modification actif.

La limite du nombre de mises à jour retourné à partir d'un jeton de modification est 100. L'attribut MoreChanges indique que le dernier jeton de modification n'est pas actualisé. D'autres modifications ont été apportées à la liste et le client doit maintenant rappeler cette méthode avec le nouveau jeton de modification.

Tableau 4 : événements de modification

Événements de modification	Description
<Id ChangeType=”InvalidToken” />	Le jeton n'est pas valide ou est ancien. Vous devez effectuer une synchronisation complète.
<Id ChangeType=”Restore” />	La liste a été restaurée à partir la Corbeille ou d'une sauvegarde. Vous devez effectuer une synchronisation complète.
<List></List>	Si le schéma de la liste a changé, ou si un jeton de modification n'a pas été fourni, la liste complète est retournée. Le format est identique à celui retourné par GetList.

Dans les deux premiers cas ci-dessus, le client doit ignorer les autres modifications et effectuer un rapprochement complet de la liste.

Tableau 5 : types de modifications

Type de modification	Description
<Id ChangeType=”Delete”>ID</Id>	Cet élément n'est plus présent. Notez que les modifications de type delete sont envoyées, même si l'élément a été éliminé par filtrage de la requête.
<Id ChangeType=”MoveAway” AfterListId=”ID” AfterItemId=”ID”>ID</Id>	Ces éléments sont traités de la même manière qu'un élément de modification de suppression, ce qui signifie qu'ils sont retournés même si l'élément a été éliminé par filtrage de la requête.
<Id ChangeType=”Restore”>ID</Id>	Cet élément et tous les éléments sous celui-ci ont été restaurés.
<Id ChangeType=”SystemUpdate”>ID</Id>	Certains clients peuvent utiliser la version masquée, l'historique des versions ou l'heure de modification pour déterminer s'il faut mettre à jour un élément. SystemUpdate signifie que Windows SharePoint Services 3.0 a apporté des modifications et que vous devez mettre à jour toutes les propriétés de cet élément particulier.
<Id ChangeType=”Rename”>ID</Id>	Les éléments renommés, tels que SystemUpdate, peuvent conserver des informations de version masquées.

Données

L'attribut ItemCount contient le nombre d'éléments retournés. Chaque élément est retourné sous la forme d'une balise <z:row>.

Un attribut ListItemCollectionPositionNext est retourné pour une synchronisation complète (pas de jeton de modification) uniquement lorsqu'un paramètre rowLimit a été utilisé pour limiter le nombre d'éléments retournés dans un appel. Ce type de pagination est bloqué sur une synchronisation incrémentielle en limitant le nombre de mises à jour qui sont traitées à partir du journal de modification au nombre limite de lignes, si ce nombre est inférieur à la limite maximale interne.

Le contenu des éléments est retourné sous la forme d'attributs avec un préfixe « ows_ » et le nom interne du champ. Les valeurs sont chiffrées en tant que valeurs d'attributs XML valides. Un ensemble de champs est toujours retourné.

Certains champs sont marqués comme étant requis et sont retournés si l'option IncludeMandatoryColumns est définie. Si <ViewFields /> est envoyé, tous les champs sont retournés.

Quand Properties=”TRUE” est défini dans la balise ViewFields, le conteneur des propriétés (le champ MetaInfo) est divisé en un attribut par propriété. Ces attributs ont un préfixe « ows_MetaInfo_ ».

La plupart des valeurs de colonne sont simplement converties à partir de leur représentation interne, tandis que d'autres sont construites spécifiquement pour un client. Plusieurs attributs dans le schéma de liste ne sont pas représentés par un champ.

Tableau 6 : attributs qui ne sont pas représentés par un champ dans le schéma de liste

Attribut	Description
MetaInfo	Conteneur de sacs de propriétés, SPListItem.Properties. Pour plus d'informations, voir le sac de propriétés dans le modèle objet SPListItem.
Champs de type « Pièces jointes » (Attachments)	Colonne Bit dans la base de données qui peut être modifiée par les options de la requête pour renvoyer des données de type pièce jointe.
RecurrenceData	Définition XML d'une périodicité. Consultez https://blogs.msdn.com/b/sharepoint/archive/2007/05/14/understanding-the-sharepoint-calendar-and-how-to-export-it-to-ical-format.aspx (éventuellement en anglais) pour plus de détails sur ce schéma XML.

MetaInfo

Conteneur de sacs de propriétés, SPListItem.Properties. Pour plus d'informations, voir le sac de propriétés dans le modèle objet SPListItem.

Champs de type « Pièces jointes » (Attachments)

Colonne Bit dans la base de données qui peut être modifiée par les options de la requête pour renvoyer des données de type pièce jointe.

RecurrenceData

Définition XML d'une périodicité.

Consultez https://blogs.msdn.com/b/sharepoint/archive/2007/05/14/understanding-the-sharepoint-calendar-and-how-to-export-it-to-ical-format.aspx (éventuellement en anglais) pour plus de détails sur ce schéma XML.

Voir aussi

Concepts

GetListItemChangesSinceToken et synchronisation des applications

Procédure : mettre à jour des éléments de liste

Partager via