message: delta

命名空间:microsoft.graph

获取指定文件夹中已添加、删除或更新的邮件集。

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

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

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

权限

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

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) Mail.ReadBasic Mail.Read、Mail.ReadWrite
委派(个人 Microsoft 帐户) Mail.ReadBasic Mail.Read、Mail.ReadWrite
应用程序 Mail.ReadBasic.All Mail.Read、Mail.ReadWrite

HTTP 请求

若要获取指定 mailFolder 中邮件中的所有更改,请执行以下操作:

GET /me/mailFolders/{id}/messages/delta
GET /users/{id}/mailFolders/{id}/messages/delta

若要专门获取在指定的 mailFolder 中创建、更新或删除的邮件,请执行以下操作:

GET /me/mailFolders/{id}/messages/delta?changeType=created
GET /users/{id}/mailfolders/{id}/messages/delta?changeType=created

GET /me/mailFolders/{id}/messages/delta?changeType=updated
GET /users/{id}/mailFolders/{id}/messages/delta?changeType=updated

GET /me/mailFolders/{id}/messages/delta?changeType=deleted
GET /users/{id}/mailFolders/{id}/messages/delta?changeType=deleted

查询参数

跟踪消息中的更改会导致一轮或多次 delta 函数调用。 如果使用除 oData 系统查询选项或自定义查询选项 changeType 以外的$deltatoken任何查询参数 (和 $skiptoken) ,则必须在初始增量请求中指定它。 Microsoft Graph 自动将指定的任意参数编码为响应中提供的 @odata.nextLink@odata.deltaLink URL 的令牌部分。 只需预先指定所需的任何查询参数一次。 在后续请求中,只需复制并应用 @odata.nextLink 上一响应中的 或 @odata.deltaLink URL,因为该 URL 已包含编码的所需参数。

查询参数 类型 说明
$deltatoken string 在上一个 delta 函数的 URL 中@odata.deltaLink返回的状态令牌调用同一消息集合,指示完成这一轮更改跟踪。 将此令牌包含在对该集合的下一组更改追踪的首次请求中,并保存和应用整个 @odata.deltaLink URL。
$skiptoken string 对之前的 delta 函数调用的 @odata.nextLink URL 中返回的状态令牌,指示同一个邮件集合中有进一步的更改需要追踪。
changeType string 自定义查询选项,用于根据更改类型筛选增量响应。 支持的值为 createdupdateddeleted

OData 查询参数

  • 像在任何 GET 请求中一样,你可以使用 $select 查询参数以仅指定获取最佳性能所需的属性。 始终返回 id 属性。
  • 对于邮件,Delta 查询支持 $select$top$expand
  • 提供对 $filter$orderby 的有限支持:
    • 唯一支持的 $filter 表达式是 $filter=receivedDateTime+ge+{value}$filter=receivedDateTime+gt+{value}
    • 唯一支持的 $orderby 表达式是 $orderby=receivedDateTime+desc。 如果不包含 $orderby 表达式,则不能保证返回顺序。
  • 不支持 $search

请求标头

名称 类型 说明
Authorization string 持有者 {token}。 必填。 详细了解 身份验证和授权
Content-Type string application/json. 必需。
Prefer string odata.maxpagesize={x}。 可选。

响应

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

示例

请求

以下示例演示了如何执行单次 delta 函数调用,并将响应正文中的邮件最大数目限制为 2。

若要跟踪文件夹中邮件中的更改,需要进行一个或多个 delta 函数调用,以获取自上次增量查询以来的增量更改集。 有关显示一轮增量查询调用的示例,请参阅 获取对文件夹中邮件的增量更改

GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGVmMDEzMTM4LTZmYWUtNDdkNC1hMDZiLTU1OGY5OTZhYmY4OAAuAAAAAAAiQ8W967B7TKBjgx9rVEURAQAiIsqMbYjsT5e-T7KzowPTAAAAAAFNAAA=/messages/delta
Prefer: odata.maxpagesize=2
响应

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

以下响应显示了 @odata.nextLink 响应头中的 skipToken

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

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

{
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/mailFolders/{id}/messages/delta?$skiptoken={_skipToken_}",
  "value": [
    {
      "receivedDateTime": "datetime-value",
      "sentDateTime": "datetime-value",
      "hasAttachments": true,
      "internetMessageId": "internetMessageId-value",
      "subject": "subject-value",
      "body": {
        "contentType": "contentType-value",
        "content": "content-value"
      }
    }
  ]
}