ChangeQuery と ChangeToken で SharePoint の変更ログを照会するQuery SharePoint change log with ChangeQuery and ChangeToken

ChangeQueryChangeToken を使用すると、SharePoint 変更ログを照会し、SharePoint コンテンツ データベース、サイト コレクション、サイト、またはリストに加えられた変更内容を取得できます。Use ChangeQuery and ChangeToken to query the SharePoint change log for changes made to a SharePoint content database, site collection, site, or list.

適用対象: SharePoint 2013 | SharePoint アドイン | SharePoint OnlineApplies to: SharePoint 2013 | SharePoint Add-ins | SharePoint Online

ChangeQueryChangeToken を使用して SharePoint 変更ログを照会すると、SharePoint コンテンツ データベース、サイト コレクション、サイト、またはリストに加えられた変更内容を検索して、処理できます。You can query the SharePoint change log by using ChangeQuery and ChangeToken to find and process changes made on a SharePoint content database, site collection, site, or list.

Core.ListItemChangeMonitor コード サンプルでは、SharePoint リストに加えられた変更を SharePoint の変更ログを使用して検索および処理する方法を紹介します。このコード サンプルは、次の操作を実行するために使用してください。The Core.ListItemChangeMonitor code sample shows you how to use SharePoint's change log to find and process changes made on a SharePoint list. Use this code sample to:

  • SharePoint をモニターして、リスト、サイト、サイト コレクションまたはコンテンツ データベースに対する変更を検出します。Monitor SharePoint for changes on a list, site, site collection, or content database.

  • リスト内のアイテムに変更が加えられた後、ビジネス プロセスを開始します。Start a business process after a change is made to an item in a list.

  • リモート イベント レシーバーを補完します。変更ログ パターンをリモート イベント レシーバー パターンと一緒に使用すると、SharePoint コンテンツ データベース、サイト コレクション、サイト、またリストに加えられたすべての変更を処理する、さらに信頼性の高いアーキテクチャが提供されます。リモート イベント レシーバーは即座に実行されますが、リモート サーバー上で実行されているため、通信エラーが発生する可能性があります。変更ログ パターンによりすべての変更が処理可能な状態に保持されますが、アプリケーションによる変更の処理は、通常、スケジュールに従って (たとえば、タイマー ジョブとして) 実行されます。これは、変更が即座には処理されないことを意味します。これら 2 つのパターンを一緒に使用すれば、同じ変更を 2 回処理する可能性を確実に回避するメカニズムを使用できます。詳細については、「 SharePoint でリモート イベント レシーバーを使用する」を参照してください。Complement your remote event receiver. Using the change log pattern with a remote event receiver pattern provides a more reliable architecture for handling all changes made to SharePoint content databases, site collections, sites, or lists. Remote event receivers run immediately, but because they run on a remote server, you might encounter a communication failure. The change log pattern ensures that all changes are available for processing, but the application processing the changes usually runs on a schedule (for example, a timer job). This means that changes are not processed immediately. If you use these two patterns together, ensure you use a mechanism to prevent processing the same change twice. For more information, see Use remote event receivers in SharePoint.

始める前にBefore you begin

まず、 Core.ListItemChangeMonitor サンプル アドインを、GitHub の Office 365 Developer Patterns and Practices プロジェクトからダウンロードします。To get started, download the Core.ListItemChangeMonitor sample add-in from the Office 365 Developer patterns and practices project on GitHub.

このコード サンプルを実行する前に、次の手順を実行します。Before you run this code sample, do the following:

  1. リストを作成する場所となる Office 365 サイトにサインインします。Sign in to your Office 365 site where you want to create the list.

  2. [サイト コンテンツ] を選択します。Choose Site Contents.

  3. [アドインの追加] を選択します。Choose add an add-in.

  4. [カスタム リスト] を選択します。Choose Custom List.

  5. [名前] に、「 TestList 」と入力します。In Name, enter TestList.

  6. [作成] を選択します。Choose Create.

このコード サンプルのデモを表示するには、次の手順を実行します。To see a demo of this code sample, perform the following steps:

  1. Visual Studio で [開始] を選択します。Choose Start in Visual Studio.

  2. Office 365 サイトの URL、リストの名前 (TestList)、および Office 365 の資格情報を入力します。コンソール アプリケーションは、TestList に対して変更が実行されるのを待機するようになります。既定では、コンソール アプリケーションは変更ログを 30 秒ごとに確認し、表示を更新します。Enter your Office 365 site's URL, the name of the list (TestList), and your Office 365 credentials. The console application now waits for changes to be made to TestList. By default, the console application checks the change log and updates the display every 30 seconds.

  3. [TestList] に新しいアイテムを追加します。Add a new item to TestList:

    1. Office 365 サイトを開き、 [サイト コンテンツ] > [TestList] に移動します。Open your Office 365 site and go to Site Contents > TestList.

    2. [新しいアイテム] を選択します。Choose new item.

    3. [タイトル] に「 MyTitle 」と入力してから、 [保存] を選択します。Enter MyTitle in Title, and then choose Save.

  4. 加えた変更がコンソール アプリケーションに表示されることを確認します。SharePoint の変更ログを強制的にコンソール アプリケーションに読み取らせるには、コンソール アプリケーションに「 r 」と入力します。Verify that your change appears in the console application. You can force the console application to read SharePoint's change log by entering r in the console application.

Core.ListItemChangeMonitor アドインを使用するUse the Core.ListItemChangeMonitor add-in

Program.cs では MainDoWork を呼び出し、SharePoint の変更ログを読み取って処理します。In Program.cs, Main calls DoWork to read and process SharePoint's change log:

  1. SharePoint の変更ログにアクセスするための ChangeQuery オブジェクトを作成します。Create a ChangeQuery object to access SharePoint's change log.

  2. 変更ログを使用し、 cq.Item = true を使用することにより変更をアイテムに返します。変更には次のものがあります。Use the change log to return changes to items by using cq.Item = true. Changes include:

    • cq.Add = true を使用して追加された新しいアイテム。New items added by using cq.Add= true.

    • cq.DeleteObject = true を使用して削除されたアイテム。Deleted items by using cq.DeleteObject = true.

    • cq.Update = true を使用して変更されたアイテム。Modified items by using cq.Update=true.

  3. ChangeToken オブジェクトを作成し、特定の時点から変更ログの変更内容を読み取ります。Create a ChangeToken object to read changes from the change log from a certain point in time.

  4. ChangeToken.StringValue に、バージョン番号、変更スコープ、TestList の GUID、変更が発生した日時、および ChangeToken の変更アイテム値 (値 -1 で初期化する) を設定します。このコード サンプルでは、変更ログから読み取る変更内容の量を制限するために、DateTime.Now.AddDays(-2).ToUniversalTime().Ticks.ToString() を使用して、変更の発生した日時を直前の 2 日間に初期化しています。Set ChangeToken.StringValue with the version number, change scope, GUID of TestList , date and time when changes occurred, and the change item value on the ChangeToken (initialize with a value of -1). This code sample limits the amount of changes read from the change log by initializing the date and time when the changes occurred to the previous two days by using DateTime.Now.AddDays(-2).ToUniversalTime().Ticks.ToString().

  5. 変更ログを、30 秒 (定数 WaitSeconds で設定する既定の待機期間) ごとに、またはユーザーが r を入力した時点で変更ログを読み取ります。変更ログを読み取るとき、コンソール アプリケーションは次の手順を実行します。Read the change log either every 30 seconds (which is the default waiting period set by the constant WaitSeconds), or when the user enters r. When reading the change log, the console application performs the following steps:

    1. List.GetChanges を使用して ChangeCollection を返します。これは、最後に変更が処理されてから後にリストに加えられた変更のコレクションです。Uses List.GetChanges to return the ChangeCollection, which is a collection of changes made to the list since the last time changes were processed.

    2. DisplayChanges を呼び出して、ChangeCollection オブジェクトに含まれる変更内容を表示します。Calls DisplayChanges to display the changes in the ChangeCollection object.

    3. 変更ログから変更を読み取る新しい時点を設定します。リストに変更があった場合 (coll に入れて返される) は、ChangeTokenStart を最後の変更の日時に設定します。Sets the new point in time to read changes from the change log. If there are changes to the list (which was returned in coll), set ChangeTokenStart to the last change's date and time.


この記事で提供されるコードは、明示または黙示のいかなる種類の保証なしに現状のまま提供されるものであり、特定目的への適合性、商品性、権利侵害の不存在についての暗黙的な保証は一切ありません。The code in this article is provided as-is, without warranty of any kind, either express or implied, including any implied warranties of fitness for a particular purpose, merchantability, or non-infringement.

private static void DoWork()
            Console.WriteLine("Url: " + url);
            Console.WriteLine("User name: " + userName);
            Console.WriteLine("List name: " + listName);

                Console.WriteLine(string.Format("Connecting to {0}", url));
                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));
                List list = results.FirstOrDefault();
                if (list == null)

                    Console.WriteLine("A list named \"{0}\" does not exist. Press any key to exit...", listName);

                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));
                        if (Console.KeyAvailable &amp;&amp; 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);

                    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("Press any key to exit...");


関連項目See also