在 Microsoft Graph 中使用 Microsoft Search API 搜索邮件Use the Microsoft Search API in Microsoft Graph to search messages

您可以使用 Microsoft 搜索 API 搜索电子邮件中的信息,返回按相关性排序的邮件,并呈现专用搜索体验。You can use the Microsoft Search API to search for information in email messages, return messages ranked by relevance, and render a dedicated search experience. 搜索适用于用户自己的邮箱中邮件的正文和附件。The search applies to the body and attachments of messages in the user's own mailbox.

重要

Microsoft Graph 连接器和 Microsoft 搜索 Api (查询和索引)当前处于预览状态。Microsoft Graph connectors and Microsoft Search APIs (query and index) are currently in preview status. 若要将连接器与 Microsoft 搜索一起使用或建立连接器,必须注册连接器预览计划To use connectors with Microsoft Search or to build connectors, you must sign up for the connectors preview program. 若要加入预览计划,请提交Microsoft Graph 连接器预览注册表单To join the preview program, submit the Microsoft Graph connectors preview sign-up form.

搜索查询可以包含最终用户在 Outlook 的 "搜索" 文本框中输入的筛选器A search query can include filters that end users enter in the Search text box in Outlook.

邮件搜索结果按receivedDateTime降序排列。Message search results are sorted by receivedDateTime in descending order.

邮件搜索适用于工作或学校帐户。Message search applies to work or school accounts. 用户可以搜索其自己的邮箱,但不能搜索委派的邮箱。Users can search their own mailbox, but can't search delegated mailboxes. 有关详细信息,请参阅已知限制For details, see known limitations.

邮件搜索还会查找附件。Message search also looks for attachments. 邮件附件搜索支持的文件类型与 SharePoint Online 搜索所支持的文件类型相同。The supported file types for message attachment search are the same as those for SharePoint Online search.

示例Examples

示例1:搜索用户邮箱中的邮件Example 1: Search messages in a user's mailbox

下面的示例查询登录用户邮箱中的邮件,其中包含邮件的任何部分(发件人姓名、主题、邮件正文或任何附件)中的字符串 "contoso"。The following example queries messages in the signed-in user's mailbox that contain the string "contoso" in any part of the message (the sender name, subject, message body, or any attachments). 查询返回前25个结果。The query returns the first 25 results. 搜索结果按日期/ 降序进行排序。The search results are ordered by DateTime descending.

请求Request

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json
{
  "requests": [
    {
      "entityTypes": [
        "message"
      ],
      "query": {
        "query_string": {
          "query": "contoso"
        }
      },
      "from": 0,
      "size": 25
    }
  ]
}

响应Response

下面是一个响应示例,其中包含一个与搜索条件相匹配的邮件。The following is an example of the response, which contains one message that matches the search criterion.

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#search",
  "value": [
    {
      "searchTerms": [
        "contoso"
      ],
      "hitsContainers": [
        {
          "total": 1,
          "moreResultsAvailable": false,
          "hits": [
            {
              "_id": "ptWLQ4o6HYpQg8xmAAATzOzRAAA=",
              "_score": 1,
              "_sortField": "DateTime",
              "_summary": "Here is a summary of your messages from last week",
              "_source": {
                "@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:搜索排名靠前的结果邮件Example 2: Search top results messages

下面的示例使用示例1中所示的搜索查询,并按相关性对结果进行排序。The following example uses the search query shown in Example 1, and sorts the results by relevance.

请求Request

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json
{
  "requests": [
    {
      "entityTypes": [
        "message"
      ],
      "query": {
        "query_string": {
          "query": "contoso"
        }
      },
      "from": 0,
      "size": 15,
      "enableTopResults": true
    }
  ]
}

已知限制Known limitations

  • 您只能访问用户自己的邮箱。You can only access a user’s own mailbox. 不支持搜索委派的邮箱。Searching delegated mailboxes is not supported.
  • 对于邮件, searchHitsContainer类型的total属性包含页面上的结果数,而不是匹配结果的总数。For messages, the total property of the searchHitsContainer type contains the number of results on the page, not the total number of matching results.

后续步骤Next steps