mailboxItem： 增量

命名空间：microsoft.graph

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

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

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

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

权限

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

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

HTTP 请求

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

查询参数

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

参数 说明
$deltaToken 针对同一项目集合的上一个增量函数调用的 URL 中deltaLink返回的状态令牌，指示该轮更改跟踪的完成情况。 将此令牌包含在对该集合的下一组更改追踪的首次请求中，并保存和应用整个 deltaLink URL。
$skipToken 在上一个增量函数调用的 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 对象的集合。

示例

请求

下面的示例演示如何进行单个增 量 函数调用并将响应正文中的最大项目数限制为 2。

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

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

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

响应

如果请求成功，响应将包含一个状态令牌，该状态令牌可能是 @odata.nextLink 响应标头) 中的 (，或者是 $skipToken@odata.deltaLink 响应标头) 中的 ($deltaToken 。 它们分别指示您是否应该继续该轮或您完成了该轮的所有更改。

下面的示例显示 $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