listItem：delta

  • 项目

命名空间：microsoft.graph

获取新创建、更新或删除 的列表项 ，而无需执行整个项目集合的完全读取。

一开始，应用不使用任何参数调用 delta。 服务开始枚举列表的层次结构，返回项页，以及 @odata.nextLink 或 @odata.deltaLink。 你的应用应继续使用 @odata.nextLink 调用，直到你看到返回 的 @odata.deltaLink 。

收到所有更改后，可以将它们应用于本地状态。 若要检查将来的更改，请使用上一响应中的 @odata.deltaLink 再次调用 delta 。

增量源显示每项的最新状态，而不是每个更改的最新状态。 如果项目重命名了两次，则仅显示一次，其最新名称为 。 由于各种原因，同一项可能会在增量源中多次出现。 应使用最后一次出现的项。

应从本地州中删除具有此属性的项。

注意： 仅当同步所有更改后为空的文件夹时，才应在本地删除该文件夹。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ❌ ❌ ❌

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） Sites.Read.All Sites.ReadWrite.All
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 Sites.Read.All Sites.ReadWrite.All

HTTP 请求

GET /sites/{siteId}/lists/{listId}/items/delta

查询参数

在请求 URL 中，可以包含以下可选查询参数。

参数 类型 说明
令牌 String 如果未指定，则枚举层次结构的当前状态。 如果 latest为 ，则返回具有最新增量令牌的空响应。 如果以前的增量令牌，则返回自该令牌以来的新状态。

此方法还支持 $select、 $expand和 $topOData 查询参数 来自定义响应。

请求标头

标头 值
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。

请求正文

请勿提供此方法的请求正文。

响应

如果成功，此方法将在响应正文中返回 200 OK 响应代码和 listItem 对象集合。

除了 listItem 对象的集合外，响应还包含以下属性之一。

名称 值 说明
@odata.nextLink URL 一个 URL，用于检索下一个可用更改页（如果当前集中存在更多更改）。
@odata.deltaLink URL 返回当前所有更改后返回的 URL，而不是 @odata.nextLink。 使用此属性可读取将来的下一组更改。

在某些情况下，服务返回一个 410 Gone 响应代码，其中包含一个错误响应，该响应包含以下错误代码之一，以及一个 Location 标头，该标头包含一个新的 nextLink ，用于启动新的增量枚举。 当服务无法为给定令牌提供更改列表时，会出现这种情况。例如，如果客户端在长时间断开连接后尝试重用旧令牌，或者服务器状态已更改并且需要新令牌。

完成完整枚举后，将返回的项与本地状态进行比较，并根据错误类型按照说明进行操作。

错误类型 说明
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 ，并且已在初始请求与此请求之间添加或修改该项，以更新本地状态。

项目的最后一页包括 @odata.deltaLink 属性，该属性提供 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": "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"
}

相关内容