跟踪驱动器更改

此方法使应用程序随着时间的推移跟踪驱动器及其子级的更改。

应用程序首先调用不带任何参数的 delta。服务开始枚举驱动器的层次结构,返回项目页面和 @odata.nextLink@odata.deltaLink,如下所述。应用程序应该使用 @odata.nextLink 继续调用,直到不再返回 @odata.nextLink,或响应内容为空更改集。

接收完所有更改后,可将这些更改应用于本地状态。若要在将来检查更改,请通过上一响应中的 @odata.deltaLink 再次调用 delta

返回具有 deleted 方面 的已删除邮件。应从本地状态中删除设置此属性的项目。

注意:如果在同步所有更改后文件夹为空,你仅应在本地删除此文件夹。

先决条件

要执行此 API,需要以下范围之一:

  • Files.Read
  • Files.Readwrite

HTTP 请求

GET /me/drive/root/delta
GET /drives/{drive-id}/root/delta
GET /groups/{group-id}/drive/root/delta

可选的查询参数

此方法支持使用 $select$expand$top OData 查询参数自定义响应。

请求正文

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

响应

如果成功,此方法在响应正文中返回 200 OK 响应代码和 DriveItem 资源集合。

除了 DriveItems 集合,此响应还包括以下属性之一:

名称 说明
@odata.nextLink url 如果当前集有其他更改,用来检索下一可用更改页的 URL。
@odata.deltaLink url 返回当前所有更改后返回的 URL,而不是 @odata.nextLink。用于在将来读取下一组更改。

示例(初始请求)

下面是一个如何调用此 API 以建立本地状态的示例。

请求

下面是一个初始请求的示例。

GET https://graph.microsoft.com/v1.0/me/drive/root/delta
响应

下面是一个响应示例。

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        },
        {
            "id": "2353010204ddgg",
            "name": "file5.txt",
            "deleted": { }
        }
    ],
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/delta(token=1230919asd190410jlka)"
}

此响应包含第一页的更改,@odata.nextLink 属性指示当前的项目集中有更多项目。在检索完所有项目页之前,你的应用程序应继续请求 @odata.nextLink 的 URL 值。

示例(集中的最后一页)

下面是一个如何调用此 API 以更新本地状态的示例。

请求

下面是一个初始请求之后的请求示例。

GET https://graph.microsoft.com/v1.0/me/drive/root/delta(token='123123901209310923!23alksjd')
响应

下面是一个响应示例。

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { },
            "deleted": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        }
    ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?(token='1230919asd190410jlka')"
}

此响应表示名为 folder2 的项目已被删除,并在初始请求和此请求之间添加或修改了 file.txt 项目以更新本地状态。

最后一页的项目将包括 @odata.deltaLink 属性,此属性提供的 URL 以后可用于检索自当前项目集起的更改。

注解

  • 增量源显示每项的最新状态,而不是每个更改的最新状态。如果项目重命名两次,它只显示一次并且使用最新名称。
  • 出于各种原因,同一项可能在增量源中出现不止一次。你应使用最后一次出现的项目。
  • 项目中的 parentReference 属性将不包括路径的值。之所以出现这种情况,是因为重命名文件夹不会导致从 delta 返回文件夹的任何后代。使用增量时应始终按 id 跟踪项目

可能会发生本服务无法为特定标记提供更改列表的情况(例如,如果客户端在连接断开很长时间后尝试重新使用旧标记,或如果服务器状态已更改并需要新标记)。在这些情况下,本服务将返回带有错误响应的 HTTP 410 Gone 错误(包含以下错误代码之一)和 Location 标头(包含从头开始全新的增量枚举的新 nextLink)。完成全部枚举后,将返回的项目与本地状态进行比较,并遵循以下说明。

错误类型 说明
resyncChangesApplyDifferences 如果确定上次同步时服务与你的本地更改保持同步,请将任意本地项目替换为服务器的版本(包括删除)。上载服务器并不知道的任意本地更改。
resyncChangesUploadDifferences 上载服务未返回的任意本地项目,并上载与服务器版本不同的任意文件(如果不知道哪个是最新的,请保留两份)。

在 OneDrive for Business 和 SharePoint 中,仅 root 文件夹支持 delta,其他文件夹并不支持。它也不会返回以下 DriveItem 属性:

  • createdBy
  • cTag
  • eTag
  • fileSystemInfo
  • lastModifiedBy
  • parentReference
  • size