使用 Microsoft 搜索 API 搜索 Outlook 邮件
使用 Microsoft Graph 中的 Microsoft 搜索 API 在电子邮件中搜索信息,返回按相关性排名的邮件,并呈现专用的搜索体验。 搜索适用于已登录用户自己的邮箱中邮件的正文和附件。
注意
测试版中的搜索 API 架构已更改。 搜索请求和响应中的某些属性已重命名或删除。 有关详细信息,请参阅 架构更改弃用警告。 本主题中的示例显示了最新的架构。
搜索查询可以包含最终用户在 Outlook 中的“搜索”文本框中输入的筛选器。
邮件搜索结果按 receivedDateTime 降序排序。
邮件搜索适用于工作或学校帐户。 用户可以搜索自己的邮箱,但不能搜索委派的邮箱。 有关详细信息,请参阅 已知限制。
邮件搜索还会查找附件。 邮件附件搜索 支持的文件类型 与 SharePoint Online 搜索的文件类型相同。
以下示例查询已登录用户邮箱中包含字符串“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"
}
}
}
}
]
}
]
}
]
}
以下示例使用示例 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 类型的 total 属性包含页面上的结果数,而不是匹配结果的总数。
- 事件不支持对结果进行排序。 请求中的 sort 子句将在响应中返回错误请求错误代码。