Interroger le journal des modifications SharePoint avec ChangeQuery et ChangeToken
Utilisez ChangeQuery et ChangeToken pour interroger le journal des modifications SharePoint pour connaître les modifications apportées à une base de données de contenu, une collection de sites, un site ou une liste SharePoint.
S’applique à : SharePoint 2013 | Compléments SharePoint | SharePoint Online
Vous pouvez interroger le journal des modifications SharePoint à l’aide de ChangeQuery et de ChangeToken pour rechercher et traiter les modifications apportées à une base de données de contenu, à une collection de sites, à un site ou à une liste SharePoint.
L’exemple de code Core.ListItemChangeMonitor vous montre comment utiliser le journal des modifications SharePoint pour rechercher et traiter les modifications apportées à une liste SharePoint. Utilisez cet exemple de code pour :
surveiller SharePoint afin de repérer les modifications apportées à une liste, à un site, à une collection de sites ou à une base de données de contenu ;
démarrer un processus métier après avoir modifié un élément dans une liste ;
compléter votre récepteur d’événements distant. L’utilisation du modèle de journal des modifications avec un modèle de récepteur d’événements distant fournit une architecture plus fiable pour le traitement de toutes les modifications apportées aux bases de données de contenu, aux collections de sites, aux sites ou aux listes SharePoint. Les récepteurs d’événements distants sont exécutés immédiatement, mais un échec de communication peut se produire en raison de leur exécution sur un serveur distant. Le modèle de journal des modifications garantit que toutes les modifications sont disponibles pour le traitement, mais l’application traitant les changements est généralement exécutée selon une planification (par exemple, un travail du minuteur). Cela signifie que les modifications ne sont pas traitées immédiatement. Si vous associez ces deux modèles, veillez à utiliser un mécanisme pour empêcher le traitement en double de la même modification. Pour obtenir plus d’informations, consultez l’article Utiliser des récepteurs d'événements distants dans SharePoint.
Avant de commencer
Pour commencer, téléchargez l’exemple de complément Core.ListItemChangeMonitor à partir du projet Pratiques et modèles Office 365 Développeur sur GitHub.
Avant d’exécuter cet exemple de code, procédez comme suit :
Connectez-vous à votre site Office 365 à l’emplacement où vous voulez créer la liste.
Choisissez Contenu du site.
Choisissez Ajouter un complément.
Choisissez Liste personnalisée.
Dans Nom, entrez TestList.
Choisissez Créer.
Pour voir une démonstration de cet exemple de code, effectuez les étapes suivantes :
Choisissez Démarrer dans Visual Studio.
Entrez l’URL de votre site Office 365, le nom de la liste (TestList) et vos informations d’identification Office 365. L’application console attend ensuite que les modifications soient apportées à TestList. Par défaut, l’application console contrôle le journal des modifications et met à jour l’affichage toutes les 30 secondes.
Ajouter un nouvel élément à TestList :
Ouvrez votre site Office 365 et accédez à Site Contents>TestList.
Choisissez Suivant.
Entrez MyTitle dans Titre, puis choisissez Enregistrer.
Vérifiez si votre modification apparaît dans l’application console. Vous pouvez forcer l’application console à lire le journal des modifications de SharePoint en entrant r dans l’application console.
Utilisation du complément Core.ListItemChangeMonitor
Dans Program.cs, Main appelle DoWork pour lire et traiter le journal des modifications de SharePoint :
Créez un objet ChangeQuery pour accéder au journal des modifications de SharePoint.
Utilisez le journal des modifications pour renvoyer les modifications aux éléments à l’aide de cq.Item = true. Les modifications incluent les éléments suivants :
les nouveaux éléments ajoutés à l’aide de cq.Add= true ;
Éléments supprimés à l’aide de cq. DeleteObject = true.
les éléments modifiés à l’aide de cq.Update=true.
Créez un objet ChangeToken pour lire les modifications à partir du journal des modifications à partir d’une certaine date.
Définissez ChangeToken.StringValue avec le numéro de version, l’étendue des modifications, le GUID de TestList, la date et l’heure auxquelles les modifications ont été apportées, et la valeur de l’élément de modification sur l’objet ChangeToken (initialiser avec une valeur de -1). Cet exemple de code limite le volume de modifications lues à partir du journal des modifications en initialisant la date et l’heure auxquelles les modifications ont été apportées sur les deux jours précédents à l’aide de DateTime.Now.AddDays(-2).ToUniversalTime().Ticks.ToString().
Lisez le journal des modifications toutes les 30 secondes (période d’attente par défaut définie par la valeur constante WaitSeconds), ou lorsque l’utilisateur entre r. Lors de la lecture du journal des modifications, l’application console effectue les étapes suivantes :
Utilise List.GetChanges pour renvoyer l’objet ChangeCollection, un ensemble des modifications apportées à la liste depuis le dernier enregistrement de modifications.
Appeler DisplayChanges pour afficher les modifications dans l’objet ChangeCollection.
Définit la nouvelle date pour lire les modifications à partir du journal des modifications. Si des modifications sont apportées à la liste (qui a été renvoyée dans coll), définissez ChangeTokenStart sur la date et l’heure de la dernière modification.
Remarque
Le code dans cet article est fourni tel quel, sans garantie d’aucune sorte, expresse ou implicite, y compris mais sans s’y limiter, aucune garantie implicite d’adéquation à un usage particulier, à une qualité marchande ou une absence de contrefaçon.
private static void DoWork()
{
Console.WriteLine();
Console.WriteLine("Url: " + url);
Console.WriteLine("User name: " + userName);
Console.WriteLine("List name: " + listName);
Console.WriteLine();
try
{
Console.WriteLine(string.Format("Connecting to {0}", url));
Console.WriteLine();
ClientContext cc = new ClientContext(url);
cc.AuthenticationMode = ClientAuthenticationMode.Default;
cc.Credentials = new SharePointOnlineCredentials(userName, password);
ListCollection lists = cc.Web.Lists;
IEnumerable<List> results = cc.LoadQuery<List>(lists.Where(lst => lst.Title == listName));
cc.ExecuteQuery();
List list = results.FirstOrDefault();
if (list == null)
{
Console.WriteLine("A list named \"{0}\" does not exist. Press any key to exit...", listName);
Console.ReadKey();
return;
}
nextRunTime = DateTime.Now;
ChangeQuery cq = new ChangeQuery(false, false);
cq.Item = true;
cq.DeleteObject = true;
cq.Add = true;
cq.Update = true;
// Set the ChangeTokenStart to two days ago to reduce how much data is returned from the change log. Depending on your requirements, you might want to change this value.
// The value of the string assigned to ChangeTokenStart.StringValue is semicolon delimited, and takes the following parameters in the order listed:
// Version number.
// The change scope (0 - Content Database, 1 - site collection, 2 - site, 3 - list).
// GUID of the item the scope applies to (for example, GUID of the list).
// Time (in UTC) from when changes occurred.
// Initialize the change item on the ChangeToken using a default value of -1.
cq.ChangeTokenStart = new ChangeToken();
cq.ChangeTokenStart.StringValue = string.Format("1;3;{0};{1};-1", list.Id.ToString(), DateTime.Now.AddDays(-2).ToUniversalTime().Ticks.ToString());
Console.ForegroundColor = ConsoleColor.Red;
Console.WriteLine(string.Format("Ctrl+c to exit. Press \"r\" key to force the console application to read the change log without waiting {0} seconds.", WaitSeconds));
Console.WriteLine();
Console.ResetColor();
do
{
do
{
if (Console.KeyAvailable && Console.ReadKey(true).KeyChar == 'r') { break; }
}
while (nextRunTime > DateTime.Now);
Console.WriteLine(string.Format("Looking for items modified after {0} UTC", GetDateStringFromChangeToken(cq.ChangeTokenStart)));
ChangeCollection coll = list.GetChanges(cq);
cc.Load(coll);
cc.ExecuteQuery();
DisplayChanges(coll, cq.ChangeTokenStart);
// If there are changes to the list (which was returned in coll), set ChangeTokenStart to the last change's date and time. This will be used as the starting point for the next read from the change log.
cq.ChangeTokenStart = coll.Count > 0 ? coll.Last().ChangeToken : cq.ChangeTokenStart;
nextRunTime = DateTime.Now.AddSeconds(WaitSeconds);
} while (true);
}
catch (Exception e)
{
Console.WriteLine(e.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
}
}