chatMessage:delta
命名空间:microsoft.graph
检索团队频道中的消息列表(无回复)。 通过使用增量查询,可以获取频道中新的或更新的消息。
请注意:增量查询将仅返回过去 8 个月内的邮件。 要检索时间更早的邮件,可使用 GET /teams/{team-id}/channels/{channel-id}/messages。
增量查询既支持可检索指定频道中的所有消息的完全同步,也支持可检索自上次同步后频道中添加或发生变化的消息的增量同步。 通常情况下,开始时会执行一次完全同步,随后会定期获取相应消息视图的增量更改。
使用 delta 函数的 GET 请求返回以下任一内容:
-
@odata.nextLink
(包含具有 delta 函数调用和skipToken
的 URL),或 -
@odata.deltaLink
(包含具有 delta 函数调用和deltaToken
的 URL)。
状态令牌对客户端是不透明的。 若要继续执行一轮更改跟踪,请将上一个 GET 请求返回的 或 @odata.deltaLink
URL 复制并应用于@odata.nextLink
该日历视图的下一个 delta 函数调用。 响应中返回的 @odata.deltaLink
表示当前一轮更改跟踪已完成。 在获取 @odata.deltaLink
) @odata.deltaLink
后,开始检索更改或发布的更多更改 (消息时,可以保存并使用该 URL。
有关详细信息,请参阅增量查询文档。
此 API 可用于以下国家级云部署。
全局服务 | 美国政府 L4 | 美国政府 L5 (DOD) | 由世纪互联运营的中国 |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
权限
为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考。
权限类型 | 最低特权权限 | 更高特权权限 |
---|---|---|
委派(工作或学校帐户) | ChannelMessage.Read.All | Group.Read.All、Group.ReadWrite.All |
委派(个人 Microsoft 帐户) | 不支持。 | 不支持。 |
应用程序 | ChannelMessage.Read.Group | ChannelMessage.Read.All、Group.Read.All、Group.ReadWrite.All |
注意
ChannelMessage.Read.Group 权限使用 特定于资源的许可。
HTTP 请求
GET /teams/{team-id}/channels/{channel-id}/messages/delta
查询参数
跟踪频道消息更改会引发一组对 delta 函数的一次或多次调用。 如果要使用任意查询参数($deltatoken
和 $skiptoken
除外),则必须在最初的 delta 请求中指定它。 Microsoft Graph 自动将指定的任意参数编码为响应中提供的 @odata.nextLink
或 @odata.deltaLink
URL 的令牌部分。
只需预先指定任何查询参数一次。
在后续请求中,可以复制并应用之前响应中返回的 @odata.nextLink
或 @odata.deltaLink
URL,因为此 URL 已包含编码参数。
查询参数 | 类型 | 说明 |
---|---|---|
$deltatoken |
string | 之前的 delta 函数调用的 @odata.deltaLink URL 中返回的状态令牌,指示该组更改跟踪的完成状态。 将此令牌包含在对该集合的下一个更改追踪迭代的首次请求中,并保存和应用整个 @odata.deltaLink URL。 |
$skiptoken |
字符串 | 上一个 delta 函数调用中的 @odata.nextLink URL 返回的状态令牌,指示需要跟踪进一步的更改。 |
OData 可选查询参数
此 API 支持以下 OData 查询参数:
-
$top
表示调用中要提取的最大消息数。 上限为 50。 -
$skip
表示列表开头要跳过的消息数。 -
$filter
,允许返回满足特定条件的消息。 支持筛选的唯一属性是lastModifiedDateTime
,且仅支持 gt 运算符。 例如,../messages/delta?$filter=lastModifiedDateTime gt 2019-02-27T07:13:28.000z
将提取 任何回复链 (每个频道的帖子和关联的回复消息) 在指定的日期时间后创建或更改。 -
$expand
允许扩展每个通道消息的属性。 仅支持 答复 。 如果通道消息包含超过 1000 条答复,replies@odata.nextLink
则会提供分页。
注意: 有关
$expand
查询参数,请参阅 列表通道消息。
请求头
标头 | 值 |
---|---|
Authorization | 持有者 {token}。 必填。 详细了解 身份验证和授权。 |
请求正文
请勿提供此方法的请求正文。
响应
如果成功,此方法在响应正文中返回 200 OK
响应代码和 chatMessage 对象集合。 该响应还包括 @odata.nextLink
URL 或 @odata.deltaLink
URL。
示例
示例 1:初始同步
以下示例显示了用于同步给定频道中消息的三个请求。 频道中有五个消息。
为简洁起见,示例响应仅显示一部分事件属性。 在实际调用中,大多数事件属性都会返回。
另请参阅如何 检索其他更改。
初始请求
本示例中,频道消息正在进行首次同步,因此初始同步请求未包含任何状态令牌。 此轮返回该日历视图中的所有事件。
请求指定可选请求标头 odata.top,每次返回 2 个事件。
GET https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$top=2
第一个请求响应
该响应包含两封邮件和一个具有 skipToken
的 @odata.nextLink
响应标头。
@odata.nextLink
URL 表示此频道中还更多邮件可获取。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(chatMessage)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$skiptoken=-FG3FPHv7HuyuazNLuy3eXlzQGbEjYLUsW9-pYkmXgn5KGsaOwrCoor2W23dGNNM1KtAX4AyvpFQNVsBgsEwUOX9lw8x9zDumgJy-C-UbjZLlZDQACyC9FyrVelZus9n.--rshdLwy_WBFJd8anPXJPbSUtUD7r3V4neB5tcrG58",
"value": [
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1606515483514",
"messageType": "message",
"createdDateTime": "2020-11-27T22:18:03.514Z",
"lastModifiedDateTime": "2020-11-27T22:18:03.514Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1606515483514?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1606515483514&parentMessageId=1606515483514",
"policyViolation": null,
"eventDetail": null,
"id": "1606515483514",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "Test"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
},
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1606691795113",
"messageType": "message",
"createdDateTime": "2020-11-29T23:16:35.113Z",
"lastModifiedDateTime": "2020-11-29T23:16:35.113Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1606691795113?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1606691795113&parentMessageId=1606691795113",
"policyViolation": null,
"eventDetail": null,
"id": "1606691795113",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "HelloWorld 11/29/2020 3:16:31 PM -08:00"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
}
]
}
第二个请求
第二个请求指定上一个响应中返回的 @odata.nextLink
URL。 请注意,无需再像在第一个请求中一样指定相同的顶级参数,因为 @odata.nextLink
URL 中的 skipToken
会将其编码并包含在内。
GET https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$skiptoken=-FG3FPHv7HuyuazNLuy3eXlzQGbEjYLUsW9-pYkmXgn5KGsaOwrCoor2W23dGNNM1KtAX4AyvpFQNVsBgsEwUOX9lw8x9zDumgJy-C-UbjZLlZDQACyC9FyrVelZus9n.--rshdLwy_WBFJd8anPXJPbSUtUD7r3V4neB5tcrG58
第二个请求响应
第二个响应返回接下来的 2 个消息和一个带有 skipToken
的 @odata.nextLink
响应标头,指示频道中存在可获取的更多消息。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(chatMessage)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$skiptoken=8UusBixEHS9UUau6uGcryrA6FpnWwMJbuTYILM1PArHxnZzDVcsHQrijNzCyIVeEauMQsKUfMhNjLWFs1o4sBS_LofJ7xMftZUfec_pijuT6cAk5ugcWCca9RCjK7iVj.DKZ9w4bX9vCR7Sj9P0_qxjLAAPiEZgxlOxxmCLMzHJ4",
"value": [
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1606691812117",
"messageType": "message",
"createdDateTime": "2020-11-29T23:16:52.117Z",
"lastModifiedDateTime": "2020-11-29T23:16:52.117Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1606691812117?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1606691812117&parentMessageId=1606691812117",
"policyViolation": null,
"id": "1606691812117",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "HelloWorld 11/29/2020 3:16:51 PM -08:00"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
},
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1606691846203",
"messageType": "message",
"createdDateTime": "2020-11-29T23:17:26.203Z",
"lastModifiedDateTime": "2020-11-29T23:17:26.203Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1606691846203?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1606691846203&parentMessageId=1606691846203",
"policyViolation": null,
"id": "1606691846203",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "HelloWorld 11/29/2020 3:17:25 PM -08:00"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
}
]
}
第三个请求
第三个请求继续使用上一个同步请求返回的最新 @odata.nextLink
。
GET https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$skiptoken=8UusBixEHS9UUau6uGcryrA6FpnWwMJbuTYILM1PArHxnZzDVcsHQrijNzCyIVeEauMQsKUfMhNjLWFs1o4sBS_LofJ7xMftZUfec_pijuT6cAk5ugcWCca9RCjK7iVj.DKZ9w4bX9vCR7Sj9P0_qxjLAAPiEZgxlOxxmCLMzHJ4
第三个请求响应
第三个响应仅返回频道中剩下的消息以及带有 deltaToken
的 @odata.deltaLink
响应标头,指示频道中的所有消息已被阅读。 保存并使用 @odata.deltaLink
URL,查询从此点开始的任何新消息。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(chatMessage)",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_y_eMWVQtBO_ejzzyIxl00ji-tQ3HzAbW4liZAVG88lO3nG_6-MBFoHY1n8y21YUzjocG-Cn1tCNeeLPLTzIe5Dw.EP9gLiCoF2CE_e6l_m1bTk2aokD9KcgfgfcLGqd1r_4",
"value": [
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1611351582080",
"messageType": "message",
"createdDateTime": "2021-01-22T21:39:42.08Z",
"lastModifiedDateTime": "2021-01-22T21:39:42.08Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1611351582080?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1611351582080&parentMessageId=1611351582080",
"policyViolation": null,
"id": "1611351582080",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "HelloWorld 1/22/2021 1:39:39 PM -08:00"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
},
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1611351603178",
"messageType": "message",
"createdDateTime": "2021-01-22T21:40:03.178Z",
"lastModifiedDateTime": "2021-01-22T21:40:03.178Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1611351603178?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1611351603178&parentMessageId=1611351603178",
"policyViolation": null,
"id": "1611351603178",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "HelloWorld 1/22/2021 1:40:00 PM -08:00"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
}
]
}
示例 2:检索其他更改
@odata.deltaLink
使用上一轮中最后一个请求中的 ,只能获取那些通过添加更改 (的消息,或从那以后在该通道中更新) 的消息。 请求应如下所示,前提是你更愿意在响应中保持相同的最大页面大小:
请求
GET https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_y_eMWVQtBO_ejzzyIxl00ji-tQ3HzAbW4liZAVG88lO3nG_6-MBFoHY1n8y21YUzjocG-Cn1tCNeeLPLTzIe5Dw.EP9gLiCoF2CE_e6l_m1bTk2aokD9KcgfgfcLGqd1r_4
响应
注意:为了提高可读性,可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(chatMessage)",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/teams/fbe2bf47-16c8-47cf-b4a5-4b9b187c508b/channels/19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/messages/delta?$deltatoken=aQdvS1VwGCSRxVmZJqykmDik_JIC44iCZpv-GLiA2VnFuE5yG-kCEBROb2iaPT_yjz2nsMoh1gXNtXii7s78HapCi5woifXqwXlVNxICh8wUUnvE2gExsa8eZ2Vy_ch5rVIhm067_1mUPML3iYUVyg.3o0rhgaBUduuxOr98An5pjBDP5JjKUiVWku3flSiOsk",
"value": [
{
"@odata.type": "#microsoft.graph.chatMessage",
"replyToId": null,
"etag": "1616989510408",
"messageType": "message",
"createdDateTime": "2021-03-29T03:45:10.408Z",
"lastModifiedDateTime": "2021-03-29T03:45:10.408Z",
"lastEditedDateTime": null,
"deletedDateTime": null,
"subject": null,
"summary": null,
"chatId": null,
"importance": "normal",
"locale": "en-us",
"webUrl": "https://teams.microsoft.com/l/message/19%3A4a95f7d8db4c4e7fae857bcebe0623e6%40thread.tacv2/1616989510408?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&tenantId=2432b57b-0abd-43db-aa7b-16eadd115d34&createdTime=1616989510408&parentMessageId=1616989510408",
"policyViolation": null,
"id": "1616989510408",
"from": {
"application": null,
"device": null,
"conversation": null,
"user": {
"@odata.type": "#microsoft.graph.teamworkUserIdentity",
"id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
"displayName": "Robin Kline",
"userIdentityType": "aadUser",
"tenantId": "e61ef81e-8bd8-476a-92e8-4a62f8426fca"
}
},
"body": {
"contentType": "text",
"content": "Hello World 28th March 2021"
},
"channelIdentity": {
"teamId": "fbe2bf47-16c8-47cf-b4a5-4b9b187c508b",
"channelId": "19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2"
},
"attachments": [],
"mentions": [],
"reactions": [],
"messageHistory": []
}
]
}