通过 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,规范化链接,移除外部媒体和导航标记。
