使用 Outlook REST API 的概述

项目
04/08/2023

提示

请在 Graph 浏览器中尝试使用示例 REST 调用。可以使用你自己的帐户，或者使用我们的一个测试帐户。探索完 API 后，请回到此处，并在左侧选择你喜爱的平台。我们将逐步指导你完成相关步骤，以便编写简单的应用程序从收件箱中检索邮件。

如果左侧尚未列出你的首选平台，请继续阅读此页。我们将介绍使用原始 HTTP 请求的同一组步骤。

本指南旨在逐步指导你完成调用 Outlook 邮件 API 以在 Office 365 和 Outlook.com 中检索邮件的流程。与平台专用入门指南不同，本指南侧重于 OAuth 和 REST 请求和响应。本指南将介绍应用在进行身份验证和检索邮件时使用的请求和响应的顺序。

本教程将使用 Microsoft Graph 来调用邮件 API。 Microsoft 建议使用 Microsoft Graph 访问 Outlook 邮件、日历和联系人。只有当需要使用 Graph 终结点上没有的功能时，才应直接使用 Outlook API（通过 https://outlook.office.com/api）。

通过本指南中的信息，你可以使用任何能够发送 HTTP 请求的语言或平台来实现此操作。

使用 OAuth2 进行身份验证

为了调用邮件 API，应用需要来自 Microsoft 标识平台的访问令牌。使用支持 OAuth 2.0 流之一获取访问令牌。

调用邮件 API

应用具有访问令牌后，即可调用邮件 API。邮件 API 参考包含所有详细信息。由于应用正在检索消息，因此它将使用对 URL 的 https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages HTTP GET 请求。这将从收件箱中检索邮件。

优化请求

应用可以使用 OData 查询参数来控制 GET 请求的行为。建议应用使用这些参数来限制返回的结果数，以及针对每一项返回的字段。来看一个示例。

考虑一个在表中显示邮件的应用程序。该表格只显示主题、发件人以及收到邮件的日期和时间。此表最多显示 25 行，并应进行排序，以便将最近收到的邮件置顶。

该应用使用以下查询参数来实现此目的：

$select 参数用于仅指定 subject、from 和 receivedDateTime 字段。
$top 参数用于指定最多 25 项。
$orderby 参数用于按 receivedDateTime 字段对结果进行排序。

这会生成以下请求。

收件箱中邮件的邮件 API 请求

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$select=subject,from,receivedDateTime&$top=25&$orderby=receivedDateTime%20DESC

Accept: application/json
Authorization: Bearer eyJ0eXAi...b66LoPVA

邮件 API 响应

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(...)/mailfolders('inbox')messages(subject,from,receivedDateTime)",
  "value": [
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABufX4i\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABufW1UAAA=",
      "subject": "Ruby on Rails tutorial",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2015-01-29T20:44:53Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABSzmz4\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABMirSeAAA=",
      "subject": "Trip Information",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-12-09T21:55:41Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAABzxiLG\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAABAblZoAAA=",
      "subject": "Multiple attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-19T20:35:59Z"
    },
    {
      "@odata.etag": "W/\"CQAAABYAAAAoPBSqxXQOT6tuE0pxCMrtAAA9yBBa\"",
      "id": "AAMkADRmMDExYzhjLWYyNGMtNDZmMC1iZDU4LTRkMjk4YTdjMjU5OABGAAAAAABp4MZ-5xP3TJnNAPmjsRslBwAoPBSqxXQOT6tuE0pxCMrtAAAAAAEMAAAoPBSqxXQOT6tuE0pxCMrtAAA9x_8YAAA=",
      "subject": "Attachments",
      "from": {
        "emailAddress": {
          "address": "jason@contoso.onmicrosoft.com",
          "name": "Jason Johnston"
        }
      },
      "receivedDateTime": "2014-11-18T20:38:43Z"
    }
  ]
}

你已经了解如何调用邮件 API，现在可以使用 API 参考来构造应用需要执行的其他任何种类调用。不过，请注意，应用需要获得应用注册时配置的适当权限，才能执行调用。