大网数据广告活动
Microsoft Graph 接口

获取文件夹中邮件的增量更改

· 52CE 我爱测

使用增量查询通过单独跟踪每个文件夹来跟踪文件夹层次结构中邮件的更改。 示例演示了如何同步文件夹中的邮件。

通过 Delta 查询,可通过一系列的 delta 函数调用来查询文件夹中邮件的添加、删除或更新。 借助 Delta 数据,能够维护和同步本地存储的用户邮件,而无需每次从服务器中提取整组用户邮件。

Delta 查询支持检索文件夹(例如,用户的收件箱)中所有邮件的完全同步,以及检索自上次同步以来该文件夹中所有已更改邮件的增量同步。通常,需要对文件夹中的所有邮件进行初始完全同步,之后可定期获取该文件夹的增量更改。

跟踪文件夹中的邮件更改

Delta 查询对每个文件夹分别执行操作。为跟踪文件夹层次结构中邮件的更改,需要分别跟踪每个文件夹。

跟踪邮件文件夹中的邮件更改通常需要使用 delta 函数按轮发出一个或多个 GET 请求。初始 GET 请求非常类似于 获取邮件,区别在于要添加 delta 函数:

GET https://graph.microsoft.com/v1.0/me/mailFolders/{id}/messages/delta

使用 delta 函数的 GET 请求返回以下任一内容:

  • @odata.nextLink(包含具有 delta 函数调用和 skipToken 的 URL),或
  • @odata.deltaLink(包含具有 delta 函数调用和 deltaToken 的 URL)。

这些令牌是对客户端完全不透明的 状态令牌。若要继续一轮邮件更改跟踪,只需将最后一个 GET 请求返回的 URL 复制并应用到同一文件夹的下一个 delta 函数调用即可。响应中返回的 @odata.deltaLink 表示当前一轮更改跟踪已完成。可以保存 @odata.deltaLink URL,并在开始下一轮时使用。

要了解如何使用 @odata.nextLink 和 @odata.deltaLink URL,请参阅下面的 示例。

在邮件的增量查询中使用查询参数

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

可选的请求标头

每个 delta 查询 GET 请求在响应中返回包含一个或多个邮件的集合。 可以视需要指定请求头 Prefer: odata.maxpagesize={x},设置响应中可包含的邮件数上限。

示例:同步文件夹中邮件

以下示例显示了对最初包含 5 个邮件的特定文件夹进行的 2 轮同步。

第一轮包含一系列用于同步文件夹中所有 5 个邮件的 3 个请求:

第一轮后,将删除其中一个邮件,并将其他邮件标记为已读。 第二轮同步仅返回 delta(删除和更新),而无需返回保持不变的其他邮件。

示例:初始请求

本示例中,指定文件夹正在进行首次同步,因此初始同步请求未包含任何状态令牌。此轮将返回该文件夹中的所有邮件。

第一个请求指定以下内容:

  • $select 参数用于在响应中返回每个邮件的 subject、sender 和 isRead 属性。
  • 可选的请求标头 odata.maxpagesize,一次返回两封邮件。
GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2

示例第一个响应

响应中返回两封邮件和一个 @odata.nextLink 响应头。@odata.nextLink URL 表示此文件夹中还更多邮件可获取。

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
      "subject": "Holiday hours update",
      "isRead": false,
      "sender": {
        "emailAddress": {
          "name": "Dana Swope",
          "address": "danas@contoso.onmicrosoft.com"
        }
      },
      "id": "AAMkADNkNAAASq35xAAA="
    },
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB/\"",
      "subject": "Holiday promotion sale",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Samantha Booth",
          "address": "samanthab@contoso.onmicrosoft.com"
        }
      },
      "id": "AQMkADNkNAAAVRMKAAAAA=="
    }
  ]
}

示例第二个请求

第二个请求指定上一个响应中返回的 @odata.nextLink URL。请注意,不再需要像第一个请求一样指定相同的 $select 参数,因为 @odata.nextLink URL 中的 skipToken 已将其编码并包含在内。

GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM HTTP/1.1
Prefer: odata.maxpagesize=2

示例第二个响应

第二个响应中返回此文件夹中接下来的 2 封邮件和另一个 @odata.nextLink(表示此文件夹中还有更多邮件可获取)。

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlqfdAAAEfYB+\"",
      "subject": "Microsoft Virtual Academy at Contoso",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Elliot Hyde",
          "address": "elliot-hyde@tailspintoys.com"
        }
      },
      "id": "AQMkADNkNAAAgWkAAAA"
    },
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB+\"",
      "subject": "New or modified user account information",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Randi Welch",
          "address": "randiw@contoso.onmicrosoft.com"
        }
      },
      "id": "AQMkADNkNAAAgWJAAAA"
    }
  ]
}

示例第三个请求

第三个请求继续使用上一个同步请求返回的最新 @odata.nextLink URL。

GET https://graph.microsoft.com/v1.0/me/mailFolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU HTTP/1.1
Prefer: odata.maxpagesize=2

示例第三个响应(即最终响应)

第三个响应中返回此文件夹中仅剩的邮件,以及表示目前已完成同步此文件夹的 @odata.deltaLink URL。保存并使用 @odata.deltaLink URL 在下一轮中同步同一文件夹。

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzFPjSbaPPxzjlzOTAAAEfYB+\"",
      "subject": "Fabric CDN now available",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Jodie Sharp",
          "address": "Jodie.Sharp@contoso.com"
        }
      },
      "id": "AAMkADk0MGFkODE3LWEAAA="
    }
  ]
}

在下一轮中同步同一文件夹中的邮件

使用上一轮中最后一个请求返回的 @odata.deltaLink,可以只获取从那以后此文件夹中发生变化(已添加、删除或更新)的邮件。假设你愿意在响应中保持页面大小上限不变,下一轮的第一个请求如下所示:

GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY HTTP/1.1
Prefer: odata.maxpagesize=2

响应包含 @odata.deltaLink。 这表示现已同步远程邮件文件夹中的所有更改。 已删除一个邮件并更改其他邮件。

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "id": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS0Dh_6qB-pB2Sa2pUum19a6YAAKnLuxoAAA=",
      "@removed": {
        "reason": "deleted"
      }
    },
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
      "subject": "Holiday hours update",
      "isRead": "true",
      "sender": {
        "emailAddress": {
          "name": "Dana Swope",
          "address": "danas@contoso.onmicrosoft.com"
        }
      },
      "id": "AAMkADNkNAAASq35xAAA="
    }
  ]
}

另请参阅

历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。

来源与署名:Microsoft 和文档贡献者(原始作者元数据 Jumaodhiss)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。

资料来源与适用范围

资料来源
Microsoft / Microsoft Graph 中文文档历史快照
适用范围
历史中文快照 2023-02-03;详见原文产品版本;文档日期 未标明
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0(文档)/ MIT(示例代码)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。