mailboxItem： delta

命名空间：microsoft.graph

获取在指定的 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 自动将指定的任意参数编码为响应中提供的 nextLink 或 deltaLink 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/v1.0/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/v1.0/$metadata#Collection(mailboxItem)",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/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="
        }
    ]
}

相关内容

  • Last updated on