mailboxItem: delta

命名空间:microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

获取一组已在指定的 mailboxFolder 中添加、删除或更新的 mailboxItem 对象。

对文件夹中的项的 delta 函数调用类似于 GET 请求,不同之处在于,通过在一个或多个调用中适当应用 状态令牌 ,可以 查询该文件夹中的项的增量更改。 此方法允许维护和同步用户邮箱项目的本地存储,而无需每次都从服务器提取整个项目集。

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

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

权限

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

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

HTTP 请求

GET /admin/exchange/mailboxes/{mailboxId}/folders/{mailboxFolderId}/items/delta

查询参数

跟踪项中的更改会引发一轮或多次 delta 函数调用。 如果要使用任意查询参数($deltaToken$skipToken 除外),则必须在最初的 delta 请求中指定它。 Microsoft Graph 自动将指定的任意参数编码为响应中提供的 nextLinkdeltaLink URL 的令牌部分。 只需预先指定所需的任何查询参数一次。 在后续请求中,只需复制并应用 nextLink 上一响应中的 或 deltaLink URL,因为该 URL 已包含编码的所需参数。

查询参数 说明
$deltaToken 在上一个 delta 函数的 URL 中deltaLink返回的状态令牌调用同一项集合,指示完成这一轮更改跟踪。 将此令牌包含在对该集合的下一组更改追踪的首次请求中,并保存和应用整个 deltaLink URL。
$skipToken 在上一个 delta 函数调用的 URL 中nextLink返回的状态令牌,指示可以在同一项集合中跟踪进一步的更改。

OData 查询参数

  • 可以使用 $select 查询参数仅指定所需的属性来获得最佳性能。 始终返回 id 属性。
  • 此增量查询支持项的 $select$top 查询参数。
  • $filter$orderby提供有限的支持:
    • 唯一支持的 $filter 表示是 $filter=receivedDateTime+ge+{value}$filter=receivedDateTime+gt+{value}
    • 唯一支持的 $orderby 表达式是 $orderby=receivedDateTime+desc。 如果未包含 $orderby 表达式,则无法保证返回顺序。
  • $search不支持查询参数。

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权
Prefer odata.maxpagesize={x}。 可选。

请求正文

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

响应

如果成功,此函数在响应正文中返回响应 200 OK 代码和 mailboxItem 对象的集合。

示例

请求

以下示例演示如何调用单个 delta 函数,并将响应正文中的最大项数限制为 2。

若要跟踪文件夹中项的更改,请进行一个或多个 delta 函数调用,以获取自上次增量查询以来的增量更改集。

有关显示一轮增量查询调用的示例,请参阅 获取对文件夹中项目的增量更改

GET https://graph.microsoft.com/beta/admin/exchange/mailboxes/MBX:e0643f21@a7809c93/folders/AAMkAGUwNjQ4ZyTAAA=/items/delta
Prefer: odata.maxpagesize=2

响应

如果请求成功,响应将包括状态令牌,该令牌可以是 $skipToken@odata.nextLink 响应标头) 中的 (,或者$deltaToken@odata.deltaLink 响应标头) 中的 (。 它们分别指示是应继续执行回合还是完成获取该回合的所有更改。

以下示例显示了 $skipToken@odata.nextLink 响应标头中的 。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-Type: application/json
Content-length: 337

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(mailboxItem)",
    "@odata.nextLink": "https://graph.microsoft.com/beta/admin/exchange/mailboxes/MBX:e0643f21@a7809c93/folders/AAMkAGUwNjQ4ZyTAAA=/items/delta?$skiptoken={_skipToken_}",
    "value": [
        {
            "@odata.type": "#microsoft.graph.mailboxItem",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAFR+6ZT\"",
            "createdDateTime": "2021-10-19T06:30:30Z",
            "lastModifiedDateTime": "2021-10-19T07:17:06Z",
            "changeKey": "CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAFR+6ZT",
            "categories": [],
            "type": "IPM.Note",
            "size": 75329,
            "id": "AAMkAGUwNjQ4ZyTAACQ2fKdhq8oSKEDSVrdi3lRAAFSX03WAAA="
        }
    ]
}