跟踪驱动器更改

项目
04/08/2023

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

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

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

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

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

权限

要调用此 API，需要以下权限之一。若要了解详细信息，包括如何选择权限的信息，请参阅权限。

权限类型	权限（从最低特权到最高特权）
委派（工作或学校帐户）	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All
委派（个人 Microsoft 帐户）	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All
应用程序	Files.Read.All、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All

HTTP 请求

GET /drives/{drive-id}/root/delta
GET /groups/{groupId}/drive/root/delta
GET /me/drive/root/delta
GET /sites/{siteId}/drive/root/delta
GET /users/{userId}/drive/root/delta

可选的查询参数

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

参数

名称	值	说明
令牌	字符串	可选。如果未指定，则枚举层次结构的当前状态。如果为 `latest`，则返回具有最新增量令牌的空响应。如果为之前的增量令牌，则返回自该令牌起的新状态。

响应

如果成功，此方法在响应正文中返回 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='1230919asd190410jlka')

响应

下面是一个响应示例。

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 以后可用于检索自当前项目集起的更改。

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

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

检索当前 deltaLink

在某些情况下，请求当前 deltaLink 值可能非常有用（无需首先枚举驱动器中已有的所有项）。

如果应用只需了解更改，不需要了解现有项，这将非常有用。若要检索最新的 deltaLink，请使用查询字符串参数 ?token=latest 调用 delta。

注意：如果尝试维护文件夹或驱动器中项目的完整本地表示形式，则必须使用 delta 进行初始枚举。如果在枚举期间发生任何写入操作，则无法保证其他方法（例如通过文件夹的 children 集合分页）返回每一个项目。使用 delta 是确保读取所需全部数据的唯一方法。

请求

GET /me/drive/root/delta?token=latest

响应

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

{
    "value": [ ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?token=1230919asd190410jlka"
}

注解

增量源显示每项的最新状态，而不是每个更改的最新状态。如果项目重命名两次，它只显示一次并且使用最新名称。
由于种种原因，同一项可能会在 delta 源中多次出现。你应使用最后一次出现的项目。
项 parentReference 上的属性不包括路径的值。这是因为重命名文件夹不会导致从 delta 返回文件夹的任何后代。 使用增量时，应始终按 ID 跟踪项目。
对于添加到驱动器的共享文件夹，delta 不会返回任何有关共享文件夹中的更改的信息。相反，应以共享文件夹自身为目标进行另一个 delta 调用。
Delta 有针对 OneDrive for Business 的额外限制；有关详细信息，请参阅发行说明以获取详细信息。

错误响应

除了上面详述的重新同步错误之外，还请参阅错误响应，详细了解错误返回方式。

通过