使用 Microsoft Graph 中的 Microsoft 搜索 API 搜索电子邮件中的信息,返回按相关性排名的消息,并呈现专用搜索体验。 搜索适用于登录用户自己的邮箱中邮件的正文和附件。
Caution: 搜索 API 架构在 beta 版本中已更改,搜索请求和响应中的某些属性已重命名或删除。 查找有关弃用的更多详细信息。 本主题中的示例显示要用于 v1.0 和 beta 中的最新架构。
搜索查询可以包含最终用户在 Outlook 的 “搜索”文本框中输入的 筛选器。
消息搜索结果按 receivedDateTime 按降序排序。
消息搜索适用于工作或学校帐户。 用户可以搜索自己的邮箱,但无法搜索委派邮箱。 有关详细信息,请参阅 已知的限制。
消息搜索还会查找附件。 消息附件搜索 支持的文件类型 与 SharePoint Online 搜索的文件类型相同。
示例 1:搜索用户邮箱中的邮件
以下示例查询登录用户邮箱中包含邮件任意部分的字符串“contoso”的邮件 (发件人名称、主题、邮件正文或) 的任何附件。 查询返回前 25 个结果。 搜索结果按 DateTime 降序排序。
请求
POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"message"
],
"query": {
"queryString": "contoso"
},
"from": 0,
"size": 25
}
]
}
响应
下面是响应的示例,其中包含一条与搜索条件匹配的消息。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
"value": [
{
"searchTerms": [
"contoso"
],
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "ptWLQ4o6HYpQg8xmAAATzOzRAAA=",
"rank": 1,
"summary": "Here is a summary of your messages from last week",
"resource": {
"@odata.type": "#microsoft.graph.message",
"createdDateTime": "2019-10-07T10:00:08Z",
"lastModifiedDateTime": "2019-10-07T10:00:11Z",
"receivedDateTime": "2019-10-07T10:00:09Z",
"sentDateTime": "2019-10-07T09:59:52Z",
"hasAttachments": false,
"subject": "Weekly digest: Microsoft 365 changes",
"bodyPreview": "Here is a summary of your messages from last week - New Feature: Live captions in English-US a",
"importance": "normal",
"replyTo": [
{
"emailAddress": {
"name": "Goncalo Torres"
}
}
],
"sender": {
"emailAddress": {
"name": "Office365 Message Center",
"address": "gtorres@contoso.com"
}
},
"from": {
"emailAddress": {
"name": "Office365 Message Center",
"address": "gtorres@contoso.com"
}
}
}
}
]
}
]
}
]
}
示例 2:搜索热门结果消息
以下示例使用示例 1 中显示的搜索查询,并按相关性对结果进行排序。
请求
POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"message"
],
"query": {
"queryString": "contoso"
},
"from": 0,
"size": 15,
"enableTopResults": true
}
]
}
响应
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
"value": [
{
"searchTerms": [
"contoso"
],
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "ptWLQ4o6HYpQg8xmAAATzOzRAAA=",
"rank": 1,
"summary": "Here is a summary of your messages from last week",
"resource": {
"@odata.type": "#microsoft.graph.message",
"createdDateTime": "2019-10-07T10:00:08Z",
"lastModifiedDateTime": "2019-10-07T10:00:11Z",
"receivedDateTime": "2019-10-07T10:00:09Z",
"sentDateTime": "2019-10-07T09:59:52Z",
"hasAttachments": false,
"subject": "Weekly digest: Microsoft 365 changes",
"bodyPreview": "Here is a summary of your messages from last week - New Feature: Live captions in English-US a",
"importance": "normal",
"replyTo": [
{
"emailAddress": {
"name": "Goncalo Torres"
}
}
],
"sender": {
"emailAddress": {
"name": "Office365 Message Center",
"address": "gtorres@contoso.com"
}
},
"from": {
"emailAddress": {
"name": "Office365 Message Center",
"address": "gtorres@contoso.com"
}
}
}
}
]
}
]
}
]
}
已知限制
- 只能访问已登录用户自己的邮箱。 不支持搜索委派邮箱。
- 对于消息,searchHitsContainer 类型的 总 属性包含页面上的结果数,而不是匹配结果的总数。
- 事件不支持对结果进行排序。 请求中的 sort 子句将在响应中返回错误的请求错误代码。
后续步骤
历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 knightsu)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
