使用 Microsoft 搜索 API 搜索 Outlook 邮件

  • 项目

使用 Microsoft Graph 中的 Microsoft 搜索 API 在电子邮件中搜索信息，返回按相关性排名的邮件，并呈现专用的搜索体验。 搜索适用于已登录用户自己的邮箱中邮件的正文和附件。

警告

测试版中的搜索 API 架构已更改。 搜索请求和响应中的某些属性已重命名或删除。 有关详细信息，请参阅 架构更改弃用警告。 本主题中的示例显示了最新的架构。

搜索查询可以包含最终用户在 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 类型的 total 属性包含页面上的结果数，而不是匹配结果的总数。
  • 事件不支持对结果进行排序。 请求中的 sort 子句将在响应中返回错误请求错误代码。

后续步骤