GetListItemChangesSinceToken の要求と応答
サードパーティのクライアントを Windows SharePoint Services と同期する最も効率的な方法は、最後の同期以後に変更されたアイテムのみをダウンロードすることです。Windows SharePoint Services 3.0 では、GetListItemChangesSinceToken Web メソッドを呼び出してこの操作を実行できます。
GetListItem では、リストからすべてのアイテムが返されます。GetListItem には、変更されたアイテムのみを取得するメソッドがありません。リストからアイテムを返す例については、「[方法] リスト アイテムを返す」を参照してください。
GetListItemChangesSinceToken メソッドを使用すると、クライアントでリストの変更を追跡できます。変更 (削除されたアイテムを含む) は、それらの変更が要求された時間を表すトークンと共に返されます。GetListItemChangesSinceToken を呼び出すときにこのトークンを含めることで、サーバーはトークンが生成された後で行われた変更のみを検索します。トークンを含めずに GetListItemChangesSinceToken 要求を送信すると、リスト スキーマ、完全なリスト内容、トークンが返されます。
注意
リスト スキーマ自体が変更されている場合は、GetListItemChangesSinceToken で、リスト スキーマ全体、完全なリスト内容、トークンが返されます。
要求オブジェクトと応答オブジェクト
要求オブジェクトと応答オブジェクトはそれぞれ、ブラウザから Web サーバーに送信される情報と、サーバーからブラウザに送信される情報を表します。要求オブジェクトは入力オブジェクトと呼ばれ、応答オブジェクトは出力オブジェクトと呼ばれます。
要求オブジェクト
GetListItemChangesSinceToken では、以下のパラメータを指定できます。
表 1: 要求パラメータ
要素 |
説明 |
|---|---|
最後の呼び出し後に行われた変更の検出に使用するトークンです。このトークンは、今後フォーマットが変更される可能性があるため、解析したり構築したりしないでください。 |
|
クエリ結果に適用される CAML フィルタです。これは、[T:Microsoft.SharePoint.SPQuery.] で「Where」句の機能を果たしています。 > [!NOTE] >query 要素には使用しないでください。 |
|
リストの表示名または GUID として表されるリストの識別子 (ID) を含む文字列です。 良好なパフォーマンスを得るには、GUID を使用することをお勧めします。GUID は波中かっこ ({}) で囲む必要があります。 |
|
返すレコードとその順番を決定するクエリを含むクエリ要素です。[GetListItems] および [SPQuery] で使用されている Collaborative Application Markup Language (CAML) クエリと類似の CAML クエリです。詳細については、Windows SharePoint Services 3.0 SDK の [GetListItems] および [SPQuery] を参照してください。 > [!NOTE] >contains パラメータとの使用は想定されていません。 |
|
SPQuery オブジェクトの各種プロパティに対する個別のノードを含む XML フラグメントです。 |
|
ページに表示するアイテム数、つまり行数を指定する文字列です。このパラメータの値は、viewName パラメータで指定されているビュー内の行数制限、およびリストの既定のビューに設定されている行数制限よりも優先されます。rowLimit は返される値の最大数です。このタグはページングに使用されます。 |
|
返すフィールドとその順番を指定します。<ViewFields /> で、リスト内のすべてのフィールドが返されます。Properties=TRUE 属性で、MetaInfo フィールドが個別のデコードされたプロパティに分けられます。 |
|
ビューの GUID を含む文字列であり、query、viewFields、rowLimit パラメータで表される属性の既定のビューを決定します。この引数が指定されていない場合、既定のビューが想定されます。指定されている場合は、query、viewFields、またはrowLimit パラメータの値が、ビュー内の対応する設定よりも優先されます。たとえば、viewFields パラメータで指定されているビューに 100 行の制限があっても、rowLimit パラメータに 1,000 が含まれている場合は、応答で 1,000 行が返されます。 |
クエリ オプションのパラメータ
queryOptions 要素には、クエリを変更するさまざまなタグを含めることができます。ブール型 (Boolean) オプションの既定値は FALSE です。Boolean オプションを有効にするには、値 TRUE (すべて大文字) を入力する必要があります。
次の表に、queryOptions パラメータによって渡される CAML (Collaborative Application Markup Language) フラグメントで使用できる要素を示します。
表 2: 使用可能なクエリ オプション タグ
要素 |
説明 |
|---|---|
< DateInUtc> |
date フィールドは、世界協定時刻 (UTC) 形式とゾーンで返されます。 UTC とは、グリニッジ標準時 (GMT) を表す国際的に認識された名称で、国際標準化機構 (ISO) の ISO8601 で指定されている形式で次のように表現されます。 2006-10-04T10:00:00Z 標準の形式では、上のようにローカル (サーバー) のタイム ゾーンで表現されますが、「T」と「Z」は、スペースで置き換えられます。 |
<ExpandUserField> |
user フィールドの値にログイン名、電子メール、SipAddress、タイトル (存在する場合) を含めるための特別なレンダリングです。これにより、user フィールドが複合ルックアップ フィールドとして機能します。 この拡張で使用するルックアップ フィールドは、Name、EMail、SipAddress、Title です。値は「,#」で区切られます。ルックアップ フィールド名の中のすべてのコンマは「,,」にエンコードされます。 次の値は、各アイテムの標準フィールド データで出現します。 [<ExpandUserField>FALSE</ExpandUserField>lookslike:ows_Author="1;#AdminAdminName"] および [<ExpandUserField>TRUE</ExpandUserField>] [Lookslike:ows_Author="1;#AdminAdminName,#login\name,#email@address,#sip@address,#AdminAdminName"] |
<ExtraIds>1,4,23</ExtraIds> |
追加のアイテムが変更されているかどうかに関係なく、それらを返されたセットに含めるために使用されます。ExtraID は一般的に、ドキュメント ライブラリで [接続先] を選択して特定のフォルダを選択するときに、同期先フォルダの ID を指定するために使用されます。ドキュメント ライブラリ全体が返されるのではなく、特定のフォルダ名が取得されます。クライアントでは、階層内でフォルダが削除されたり、名前が変更された時間を検出できます。 > [!NOTE] >このタグは、変更トークンでのみ使用する必要があります。 リストに対する何らかの変更が完了し、変更されたアイテムをフェッチするクエリで ID が使用されていない限り、フォルダ名は返されません。 |
<Folder> |
ビューのルート フォルダの範囲を設定します。これはサーバー相対 URL です。 <Folder>Shared Documents/foldername</Folder> |
<IncludeAttachmentUrls> |
Attachments フィールドに返される値を、ブール型 (Boolean) から ;# で区切られた完全 URL のリストに変更します。 |
<IncludeAttachmentVersion> |
IncludeAttachmentUrls と共に使用します。このタグは、更新を検証するときに競合の検出に使用される GUID とバージョン番号を返します。 |
<IncludeMandatoryColumns> |
viewFields で指定されていなくても、必須であると定義されているフィールドが含まれていることを確認します。Windows SharePoint Services 3.0 には、このオプションとは無関係に常に返される必須フィールドのセットが別に存在するため、このオプションを誤解しないように注意してください。 |
<IncludePermissions> |
個々のアイテムのアクセス許可を要求するために、クライアントから使用できるメソッドの一つです。個々のアイテムのアクセス許可を要求するには TRUE を指定します。 |
<MeetingInstanceId> |
整数値。正の数は個別の会議インスタンスを表します。負の数には、次の意味があります : -3 = UnSpecified、-2 = AllWithSeries、-1 = AllButSeries、0 = Seriesこの要素は省略できます。既定値は -1 です。負の値は Microsoft.SharePoint.Meetings.SPMeeting.SpecialInstance 列挙体の値に対応します。 |
<OptimizeFor> |
サポートされている値は、次のとおりです。
クエリまたは定期的なアイテムの順序が要求されていない限り、既定値は ItemIds です。このタグにより、SQL Server クエリが ID 順で最適化されます。 FolderUrls は、SQL Server クエリを DirName、LeafName 順序で最適化して、1 つまたは複数のフォルダのフラットな内容にフィルタ処理されている同期を最適化します。 <OptimizeFor>ItemIds</OptimizeFor> |
<Paging ListItemCollectionPositionNext=”X” /> |
X は返すアイテムのページを決定するために使用されるトークンです。changeToken 値と同様に、このトークンを解析または構築しないでください。 |
<RecurrenceOrderBy> |
これは一部の予定表プログラムでの要件です。それぞれの定期的な系列で、最初にマスタ アイテムが返されてから、すべての例外が返されます。これは、他のどの順序付けよりも先に適用される、内部の特別な順序付けです。 > [!NOTE] >プログラムで明示的に必要とされていない限り、このオプションを使用しないでください。 ビューに種類が Recurrence のフィールドがある場合、リストは参照の種類の固有識別子 (UID) のフィールドで順序付けられ、定期的なアイテムのフィールドの定義に EventType と StartDate が含められます。 |
<RecurrencePatternXMLVersion> |
下位互換性の維持のために使用されます。RecurrencePatternXMLVersion は、RecurrenceData フィールドの値が <V3RecurrencePattern /> を返さないように変更します。このタグを含めると、Windows SharePoint Services 3.0 にとって未知の定期的なパターンが正常に送信されるようになります。 |
<ViewAttributes > |
GetView メソッドでビューを取得するときに、View 要素の一部として返されるすべての属性を表す文字列です。この要素は省略可能で、既定値は空です。ライブラリ内のすべてのドキュメントを返すには、ViewAttributes 要素を次のように使用します : <ViewAttributes Scope=”Recursive” />。 |
既定のクエリ オプション
queryOptions 要素が指定されていない場合、次の既定のオプションが使用されます。
DateInUtc = TRUE
ExpandUserField = TRUE
IncludePermissions = TRUE
IncludeAttachmentUrls = TRUE
IncludeAttachmentVersion = TRUE
MeetingInstanceID = -1
RecurrenceOrderBy = TRUE
RecurrencePatternXMLVersion = v3
ViewAttributes Scope = 'Recursive'
注意
クライアントからは、常にクエリ オプションを指定することを推奨します。指定しないと、スケール パフォーマンスに悪影響を与えます。
応答オブジェクト
GetListItemChangesSinceToken 応答は、次に示す XML 形式で配信されます。このフラグメントにはすべての変更が含まれており、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>
リストとグローバル プロパティ
次の表では、戻り値パラメータについて説明します。
表 3: リターン パラメータ
パラメータ |
定義 |
|---|---|
代替 URL は、イントラネット ゾーン、既定のゾーン、エクストラネット ゾーン、インターネット ゾーン、カスタム ゾーンの順にコンマ区切りで列挙されます。 |
|
SPList.EffectiveBasePermissions.ToString() プロパティによって返されるリストのアクセス許可です。 |
|
クライアントに同期する必要がある内容のメガバイト (MB) 単位の合計サイズです。既定値は 500 MB です。GetListItemChangesSinceToken を呼び出して各ドキュメントの URL とメタデータを取得できますが、実際のドキュメント内容を取得するには HTTP GET を実行する必要があります。 |
|
ユーザーが開始する同期、または自動同期の最短間隔を表すサーバー パラメータです。値は分単位の時間を表します。 > [!NOTE] >ユーザーが手動同期を開始しても、クライアントではこの値が使用されます。つまり、この値に 5 分が設定されている場合は、ユーザーが [送受信] を繰り返しクリックしてもクライアントからは 5 分ごとに 1 回の要求のみ送信されます。 |
|
推奨される同期の最短間隔です。この値は自動同期よりも優先されます。クライアントでは推奨される間隔を超える頻度の自動同期は実行されません。 |
変更イベント
変更は、クライアントによって処理される必要がある変更イベントのリストで構成されています。
これらの変更イベントは、変更トークンが指定されている場合に内部の変更ログから取得されます。完全な同期 (変更トークンなし) の場合でも、現在の変更トークンと共に変更タグが返されます。
変更トークンから返される更新の個数は 100 に制限されます。MoreChanges 属性は、最後の変更トークンが最新ではないことを示します。リストに対して追加の変更が行われているため、新しい変更トークンを使用してクライアントからこのメソッドを再度呼び出す必要があります。
表 4: 変更イベント
変更イベント |
説明 |
|---|---|
<Id ChangeType=”InvalidToken” /> |
トークンが無効か、古くなっています。完全な同期を実行する必要があります。 |
<Id ChangeType=”Restore” /> |
リストがごみ箱またはバックアップから復元されました。完全な同期を実行する必要があります。 |
<List></List> |
リスト スキーマが変更された場合、または変更トークンが指定されなかった場合は、完全なリストが返されます。リスト形式は、GetListによって返されるものと同じです。 |
上記の最初の 2 つの場合は、クライアントは他の変更を無視し、リストの完全な照合を実行します。
表 5: 変更の種類
変更の種類 |
説明 |
|---|---|
<Id ChangeType=”Delete”>ID</Id> |
このアイテムは既に存在していません。クエリでこのアイテムが除外されている場合でも delete 変更が送信されることに注意してください。 |
<Id ChangeType=”MoveAway” AfterListId=”ID” AfterItemId=”ID”>ID</Id> |
これらのアイテムは、delete 変更アイテムと同様に処理されます。つまり、クエリでこれらのアイテムが除外されている場合でもアイテムが返されます。 |
<Id ChangeType=”Restore”>ID</Id> |
このアイテムとその下のすべてのアイテムが復元されました。 |
<Id ChangeType=”SystemUpdate”>ID</Id> |
一部のクライアントでは、非表示のバージョン、バージョン履歴、または更新日時を使用してアイテムの更新が決定されます。SystemUpdate である場合、Windows SharePoint Services 3.0 で変更が実行され、その特定アイテムのすべてのプロパティの更新が必要なことを意味します。 |
<Id ChangeType=”Rename”>ID</Id> |
名前が変更されたアイテムは、SystemUpdate と同様に非表示のバージョン情報を保持できます。 |
データ
ItemCount 属性には、返されたアイテムの数が含まれています。各アイテムは <z:row> タグとして返されます。
ListItemCollectionPositionNext 属性は、完全な同期 (変更トークンなし) に対して返されますが、これは 1 回の呼び出しで返されるアイテムの数を制限するために rowLimit パラメータを使用している場合に限られます。行制限数が内部の最大制限数よりも小さい場合に、変更ログから処理される更新数が行制限数に制限され、この種類のページングは増分同期でブロックされます。
アイテムの内容は、“ows_”プレフィックスとフィールドの内部名で構成される属性で返されます。これらの値は有効な XML 属性の値としてエンコードされます。常にフィールドのセットが返されます。
一部のフィールドは必須としてマークされており、IncludeMandatoryColumns オプションが設定されている場合に返されます。<ViewFields /> を送信すると、すべてのフィールドが返されます。
ViewFields タグ内で Properties=”TRUE”が設定されている場合、プロパティ バッグ (MetaInfo フィールド) は、プロパティごとに 1 つの属性に分割されます。これらの属性には、“ows_MetaInfo_”プレフィックスが付けられます。
列の値のほとんどは、それらの内部表現を単純に変換したもので、それ以外はクライアント用に個別に構築したものです。リスト スキーマ内のいくつかの属性は、フィールドでは表現されません。
表 6: フィールドで表現されないリスト スキーマ内の属性
属性 |
説明 |
|---|---|
MetaInfo |
プロパティ バッグ コンテナである SPListItem.Properties です。詳細については、SPListItem オブジェクトのプロパティ バッグを参照してください。 |
種類が “Attachments” のフィールド |
attachment データを返すためにクエリ オプションで変更できる、データベース内のビット列です。 |
RecurrenceData |
定期的な予定の XML 定義です。 この XML スキーマの詳細については、https://blogs.msdn.com/sharepoint/archive/2007/05/14/understanding-the-sharepoint-calendar-and-how-to-export-it-to-ical-format.aspx を参照してください。 |