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

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.

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

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

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

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

Voir aussi

Concepts

GetListItemChangesSinceToken et synchronisation des applications

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