Общие сведения об использовании REST API Outlook

Статья
04/08/2023

Совет

Попробуйте примеры вызовов REST в песочнице Graph. Вы можете использовать собственную учетную запись или одну из тестовых учетных записей. Изучив работу API, вернитесь сюда и выберите нужную платформу слева. Мы поможем вам создать простое приложение для получения сообщений из папки "Входящие".

Если нужной вам платформы еще нет в списке, продолжайте читать эту статью. Мы выполним те же действия, используя необработанные HTTP-запросы.

В этом руководстве описывается вызов API Почты Outlook для получения сообщений из Office 365 и Outlook.com. В отличие от инструкций по началу работы для конкретных платформ, в этом руководстве рассматриваются запросы и ответы OAuth и REST. В нем описана последовательность запросов и ответов, которую использует приложение для проверки подлинности и получения сообщений.

В этом руководстве для вызова API почты будет использоваться Microsoft Graph. Корпорация Майкрософт рекомендует использовать Microsoft Graph для доступа к почте, календарю и контактам Outlook. Использовать API Outlook напрямую (через https://outlook.office.com/api) следует, только если вам требуется функция, недоступная в конечных точках Graph.

Сведения из данного руководства помогут вам реализовать этот сценарий на любом языке и на любой платформе, поддерживающей HTTP-запросы.

Проверка подлинности с помощью OAuth2

Чтобы вызвать API Почты, приложению необходим маркер доступа из платформы удостоверений Майкрософт. Чтобы получить маркер доступа, используйте один из поддерживаемых потоков OAuth 2.0.

Вызов API почты

После получения маркера доступа приложение готово к вызову API Почты. Справочник по API Почты содержит все необходимые сведения. Так как приложение получает сообщения, оно будет отправлять запрос HTTP GET на URL-адрес https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages. Так оно получит сообщения из папки "Входящие".

Параметры запроса

Вы можете управлять запросами GET в приложении с помощью параметров запроса OData. Рекомендуем использовать эти параметры для ограничения числа возвращаемых результатов, а также полей, возвращаемых по каждому элементу. Рассмотрим эти действия на примере.

Представьте приложение, которое показывает сообщения в таблице. В ней отображаются только тема, отправитель, дата и время получения сообщения. Таблица содержит не более 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. Обратите внимание, что необходимые для вызовов разрешения настраиваются во время регистрации приложения.