listItem: delta
名前空間: microsoft.graph
重要
Microsoft Graph の /beta
バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
アイテム コレクション全体の完全な読み取りを実行することなく、新しく作成、更新、または削除された リスト アイテムを取得します。
アプリでは、最初にパラメーターを指定せずに delta
を呼び出します。
このサービスでは、リストの階層の列挙、項目のページの返し、 @odata.nextLink または @odata.deltaLink のいずれかが開始されます。
@odata.deltaLink が返されるまで、アプリは @odata.nextLink で呼び出しを続ける必要があります。
すべての変更を受け取った後、それらをローカル状態に適用できます。
将来の変更をチェックするには、前の応答から @odata.deltaLink を使用してもう一度を呼び出delta
します。
差分フィードは各変更を示すのではなく、各アイテムの最新の状態を示すものです。 項目の名前が 2 回変更された場合、最新の名前で表示されるのは 1 回だけです。 さまざまな理由で、同じ項目がデルタ フィードに複数回表示される場合があります。 その場合は最後に出現したものを使用する必要があります。
削除された項目は、 削除 されたファセットと共に返されます。 Deleted
は、アイテムが削除され、復元できないことを示します。
このプロパティを持つ項目は、ローカル状態から削除する必要があります。
メモ: フォルダーは、すべての変更を同期した後に空の場合にのみ、ローカルで削除する必要があります。
この API は、次の国内クラウド展開で使用できます。
グローバル サービス | 米国政府機関 L4 | 米国政府機関 L5 (DOD) | 21Vianet が運営する中国 |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
アクセス許可
この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。
アクセス許可の種類 | 最小特権アクセス許可 | 特権の高いアクセス許可 |
---|---|---|
委任 (職場または学校のアカウント) | Sites.Read.All | Sites.ReadWrite.All |
委任 (個人用 Microsoft アカウント) | サポートされていません。 | サポートされていません。 |
アプリケーション | Sites.Read.All | Sites.ReadWrite.All |
HTTP 要求
GET /sites/{siteId}/lists/{listId}/items/delta
クエリ パラメーター
要求 URL には、次の省略可能なクエリ パラメーターを含めることができます。
パラメーター | 型 | 説明 |
---|---|---|
token | String | 指定されていない場合は、階層の現在の状態を列挙します。 の場合 latest は、最新のデルタ トークンを含む空の応答が返されます。 以前のデルタ トークンの場合は、そのトークン以降の新しい状態を返します。 |
このメソッドでは、応答を $select
カスタマイズするための、、 $expand
、および $top
OData クエリ パラメーター もサポートされています。
要求ヘッダー
ヘッダー | 値 |
---|---|
Authorization | ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。 |
要求本文
このメソッドには、要求本文を指定しません。
応答
成功した場合、このメソッドは 200 OK
応答コードと、応答本文で listItem オブジェクトのコレクションを返します。
listItem オブジェクトのコレクションに加えて、応答には次のいずれかのプロパティも含まれます。
名前 | 値 | 説明 |
---|---|---|
@odata.nextLink | URL | 現在のセットにさらに変更がある場合は、次に使用可能な変更ページを取得する URL。 |
@odata.deltaLink | URL | 現在のすべての変更が返された後に、@odata.nextLink の代わりに返される URL です。 このプロパティを使用して、今後の変更の次のセットを読み取ります。 |
場合によっては、サービスは、次のいずれかのエラー コードを含むエラー応答とLocation
、新しいデルタ列挙を開始する新しいnextLink
を含むヘッダーを含む応答コードを返410 Gone
します。 これは、サービスが特定のトークンの変更の一覧を提供できない場合に発生します。たとえば、クライアントが長時間切断された後に古いトークンを再利用しようとした場合や、サーバーの状態が変更され、新しいトークンが必要な場合などです。
完全な列挙が完了したら、返された項目をローカル状態と比較し、エラーの種類に基づいて指示に従います。
エラーの種類 | 手順 |
---|---|
resyncChangesApplyDifferences |
最後に同期したときに、サービスがローカルの変更で最新の状態であったと確信している場合は、ローカル項目をサーバーからのバージョン (削除を含む) に置き換えます。 サーバーが把握していないすべてのローカル変更をアップロードします。 |
resyncChangesUploadDifferences |
サービスが返さなかったローカルアイテムをアップロードし、サーバーのバージョンと異なるアイテムをアップロードします。 どちらのコピーが最新のものであるかわからない場合は、両方のコピーを保持します。 |
再同期エラーに加え、エラーが返される方法の詳細については、「 Microsoft Graph のエラー応答とリソースの種類」を参照してください。
例
例 1: 最初の要求
次の例は、初期要求と、この API を呼び出してローカル状態を確立する方法を示しています。
要求
次の例は、最初の要求を示しています。
GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta
応答
次の例は、変更の最初のページと、現在の項目セットで使用可能な項目がそれ以上ないことを示す @odata.nextLink プロパティを含む応答を示しています。 アプリは、アイテムのすべてのページが取得されるまで、@odata.nextLink の URL の値を要求し続ける必要があります。
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"createdDateTime": "2020-06-02T22:46:58Z",
"eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
"id": "1",
"lastModifiedDateTime": "2021-10-14T23:27:27Z",
"webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
"createdBy": {
"user": {
"displayName": "John doe"
}
},
"parentReference": {
"id": "1",
"path": "Shared%20Documents",
"siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
},
"contentType": {
"id": "0x00123456789abc",
"name": "Folder"
}
},
{
"createdDateTime": "2020-06-02T22:46:58Z",
"eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC067},756\"",
"id": "2",
"lastModifiedDateTime": "2021-10-14T23:27:27Z",
"webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemA.txt",
"createdBy": {
"user": {
"displayName": "John doe"
}
},
"parentReference": {
"id": "2",
"path": "Shared%20Documents",
"siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
},
"contentType": {
"id": "0x00123456789abc",
"name": "Document"
}
},
{
"createdDateTime": "2020-06-02T22:46:58Z",
"eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC068},756\"",
"id": "3",
"lastModifiedDateTime": "2021-10-14T23:27:27Z",
"webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemB.txt",
"createdBy": {
"user": {
"displayName": "John doe"
}
},
"parentReference": {
"id": "3",
"path": "Shared%20Documents",
"siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
},
"contentType": {
"id": "0x00123456789abc",
"name": "Document"
}
}
],
"@odata.nextLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}
例 2: 最後のページ要求
次の例は、セット内の最後のページを取得する要求と、この API を呼び出してローカル状態を更新する方法を示しています。
要求
次の例は、最初の要求の後の要求を示しています。
GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka
応答
次の例は、という名前 TestItemB.txt
の項目が削除され、項目が最初の TestFolder
要求とこの要求の間で追加または変更され、ローカル状態を更新したことを示す応答を示しています。
アイテムの最後のページには、現在の項目セット以降の変更を取得するために後で使用できる URL を提供する @odata.deltaLink プロパティが含まれています。
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"createdDateTime": "2020-06-02T22:46:58Z",
"eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
"id": "1",
"lastModifiedDateTime": "2016-03-21T20:01:37Z",
"webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
"createdBy": {
"user": {
"displayName": "John doe"
}
},
"parentReference": {
"id": "1",
"path": "Shared%20Documents",
"siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
},
"contentType": {
"id": "0x00123456789abc",
"name": "Folder"
}
},
{
"id": "3",
"parentReference": {
"siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
},
"contentType": {
"id": "0x00123456789abc",
"name": "Document"
},
"deleted": {
"state": "deleted"
}
}
],
"@odata.deltaLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}
例 3: デルタ リンク要求
一部のシナリオでは、最初にリスト内のすべての項目を既に列挙せずに、現在 deltaLink
の値を要求できます。 これは、アプリが変更についてのみ知りたいため、既存の項目について知る必要がない場合に便利です。
最新deltaLink
の を取得するには、クエリ文字列パラメーター を指定して を呼び出しますdelta
?token=latest
。
要求
次の例は要求を示しています。
GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=latest
応答
次の例は応答を示しています。
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [ ],
"@odata.deltaLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}
関連コンテンツ
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示