次の方法で共有


listItem: delta

名前空間: microsoft.graph

アイテム コレクション全体の完全な読み取りを実行することなく、新しく作成、更新、または削除された リスト アイテムを取得します。

アプリでは、最初にパラメーターを指定せずに delta を呼び出します。 このサービスでは、リストの階層の列挙、項目のページの返し、 @odata.nextLink または @odata.deltaLink のいずれかが開始されます。 @odata.deltaLink が返されるまで、アプリは @odata.nextLink で呼び出しを続ける必要があります。

すべての変更を受け取った後、それらをローカル状態に適用できます。 今後の変更を確認するには、前の応答から @odata.deltaLink を使用してdeltaをもう一度呼び出します。

差分フィードは各変更を示すのではなく、各アイテムの最新の状態を示すものです。 項目の名前が 2 回変更された場合、最新の名前で表示されるのは 1 回だけです。 さまざまな理由で、同じ項目がデルタ フィードに複数回表示される場合があります。 その場合は最後に出現したものを使用する必要があります。

このプロパティを持つ項目は、ローカル状態から削除する必要があります。

手記: フォルダーは、すべての変更を同期した後に空の場合にのみ、ローカルで削除する必要があります。

この 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$topOData クエリ パラメーター もサポートされています。

要求ヘッダー

ヘッダー
Authorization ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。

要求本文

このメソッドには、要求本文を指定しません。

応答

成功した場合、このメソッドは 200 OK 応答コードと、応答本文で listItem オブジェクトのコレクションを返します。

listItem オブジェクトのコレクションに加えて、応答には次のいずれかのプロパティも含まれます。

名前 説明
@odata.nextLink URL 現在のセットにさらに変更がある場合に、次に使用可能な変更ページを取得する URL。
@odata.deltaLink URL 現在のすべての変更が返された後に、@odata.nextLink の代わりに返される URL です。 このプロパティを使用して、今後の変更の次のセットを読み取ります。

場合によっては、サービスは、次のいずれかのエラー コードを含むエラー応答と、新しいデルタ列挙を開始する新しいnextLinkを含むLocation ヘッダーを含む410 Gone応答コードを返します。 これは、サービスが特定のトークンの変更の一覧を提供できない場合に発生します。たとえば、クライアントが長時間切断された後に古いトークンを再利用しようとした場合や、サーバーの状態が変更され、新しいトークンが必要な場合などです。

完全な列挙が完了したら、返された項目をローカル状態と比較し、エラーの種類に基づいて指示に従います。

エラーの種類 手順
resyncChangesApplyDifferences 最後に同期したときに、サービスがローカルの変更で最新の状態であったと確信している場合は、ローカル項目をサーバーからのバージョン (削除を含む) に置き換えます。 サーバーが把握していないすべてのローカル変更をアップロードします。
resyncChangesUploadDifferences サービスが返さなかったローカルアイテムをアップロードし、サーバーのバージョンと異なるアイテムをアップロードします。 どちらのコピーが最新のものであるかわからない場合は、両方のコピーを保持します。

再同期エラーに加え、エラーが返される方法の詳細については、「 Microsoft Graph のエラー応答とリソースの種類」を参照してください。

例 1: 最初の要求

次の例は、初期要求と、この API を呼び出してローカル状態を確立する方法を示しています。

要求

次の例は、最初の要求を示しています。

GET https://graph.microsoft.com/v1.0/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/v1.0/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/v1.0/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/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

一部のシナリオでは、最初にリスト内のすべての項目を既に列挙せずに、現在の deltaLink 値を要求できます。 これは、アプリが変更についてのみ知りたいため、既存の項目について知る必要がない場合に便利です。 最新のdeltaLinkを取得するには、クエリ文字列パラメーター ?token=latest を使用して delta を呼び出します。

要求

次の例は要求を示しています。

GET https://graph.microsoft.com/v1.0/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/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}