Общие сведения об использовании REST API OutlookOverview of using the Outlook REST APIs

Совет

Попробуйте примеры вызовов REST в песочнице Graph. Вы можете использовать собственную учетную запись или одну из тестовых учетных записей. Изучив работу API, вернитесь сюда и выберите нужную платформу слева. Мы поможем вам создать простое приложение для получения сообщений из папки "Входящие".Try out sample REST calls in the Graph Explorer. You can use your own account, or one of our test accounts. Once you're done exploring the API, come back here and select your favorite platform on the left. We'll guide you through the steps to write a simple application to retrieve messages from your inbox.

Если нужной вам платформы еще нет в списке, продолжайте читать эту статью. Мы выполним те же действия, используя необработанные HTTP-запросы.If your preferred platform isn't listed yet, continue reading on this page. We'll go through the same set of steps using raw HTTP requests.

В этом руководстве описывается вызов API Почты Outlook для получения сообщений из Office 365 и Outlook.com. В отличие от инструкций по началу работы для конкретных платформ, в этом руководстве рассматриваются запросы и ответы OAuth и REST. В нем описана последовательность запросов и ответов, которую использует приложение для проверки подлинности и получения сообщений.The purpose of this guide is to walk through the process of calling the Outlook Mail API to retrieve messages in Office 365 and Outlook.com. Unlike the platform-specific getting started guides, this guide focuses on the OAuth and REST requests and responses. It will cover the sequence of requests and responses that an app uses to authenticate and retrieve messages.

В этом руководстве для вызова API почты будет использоваться Microsoft Graph.This tutorial will use Microsoft Graph to call the Mail API. Корпорация Майкрософт рекомендует использовать Microsoft Graph для доступа к почте, календарю и контактам Outlook.Microsoft recommends using Microsoft Graph to access Outlook mail, calendar, and contacts. Использовать API Outlook напрямую (через https://outlook.office.com/api) следует, только если вам требуется функция, недоступная в конечных точках Graph.You should use the Outlook APIs directly (via https://outlook.office.com/api) only if you require a feature that is not available on the Graph endpoints.

Сведения из данного руководства помогут вам реализовать этот сценарий на любом языке и на любой платформе, поддерживающей HTTP-запросы.With the information in this guide, you can implement this in any language or platform capable of sending HTTP requests.

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

Чтобы вызвать API Почты, приложению необходим маркер доступа из Azure Active Directory. Для этого приложение реализует один из поддерживаемых потоков OAuth в конечной точке Azure версии 2.0. Однако перед этим приложение необходимо зарегистрировать на портале регистрации приложений.In order to call the Mail API, the app requires an access token from Azure Active Directory. In order to do that, the app implements one of the supported OAuth flows in the Azure v2.0 endpoint. However, before this will work, the app must be registered in the Application Registration Portal.

Регистрация приложенияRegistering an app

Примечание

В этом примере будет использоваться поток кода авторизации.This example scenario will use the authorization code flow. Действия для неявного потока и потока учетных данных клиента будут немного отличаться.The steps for the implicit flow or client credentials flow will be slightly different.

Вы можете использовать Центр администрирования Azure Active Directory, чтобы быстро зарегистрировать приложение, которое использует любое из API Outlook в Microsoft Graph.You can use the Azure Active Directory admin center to quickly register an app that uses any of the Outlook APIs in Microsoft Graph.

Важно!

Требования к учетной записиAccount requirements

Чтобы использовать центр администрирования Azure Active Directory, необходима рабочая или учебная учетная запись Office 365 либо учетная запись Майкрософт.In order to use the Azure Active Directory admin center, you need either an Office 365 work or school account, or a Microsoft account. Если у вас нет ни одной из этих учетных записей, вы можете выполнить одно из следующих действий:If you don't have either of these, you have a number of options:

Зарегистрировав приложение, вы получите идентификатор и секрет клиента.Once you register the app, you will have a client ID and secret. Они используются в потоке кода авторизации.These are used in the authorization code flow.

Получение кода авторизацииGetting an authorization code

Чтобы использовать поток кода авторизации, сначала необходимо получить код. Приложение получает код из Azure, когда пользователь входит и подтверждает необходимый уровень доступа.The first step in the authorization code flow is to get an authorization code. That code is returned to the app by Azure when the user logs on and consents to the level of access the app requires.

Сначала приложение создает URL-адрес для входа пользователя. Этот URL-адрес нужно открыть в браузере, чтобы пользователь мог войти и предоставить требуемые разрешения.First the app constructs a logon URL for the user. This URL must be opened in a browser so that the user can login and provide consent.

Базовый URL-адрес для входа выглядит так:The base URL for logon looks like:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Приложение добавляет параметры запроса в базовый URL-адрес, чтобы служба Azure могла определить, какое приложение запрашивает вход и какие разрешения ему требуются.The app appends query parameters to this base URL to let Azure know what app is requesting the logon, and what permissions it is requesting.

  • client_id. Идентификатор клиента, создаваемый при регистрации приложения. С его помощью Azure определяет приложения, которые запрашивают вход.client_id: the client ID generated by registering the app. This lets Azure know which app is requesting the logon.
  • redirect_uri. Адрес, на который Azure перенаправит пользователя после того, как он предоставит приложению разрешение. Это значение должно соответствовать значению URI перенаправления, которое использовалось при регистрации приложения.redirect_uri: the location that Azure will redirect to once the user has granted consent to the app. This value must correspond to the value of Redirect URI used when registering the app.
  • response_type. Тип ответа, который ожидает приложение. Для потока предоставления авторизации всегда должно быть задано значение code.response_type: the type of response the app is expecting. For the Authorization Grant Flow, this should always be code.
  • scope: разделенный пробелами список областей доступа, необходимых приложению.scope: a space-delimited list of access scopes that your app requires. Полный список областей Outlook в Microsoft Graph см. в статье Области разрешений Microsoft Graph.For a full list of Outlook scopes in Microsoft Graph, see Microsoft Graph permission scopes.

Например, приложение, которому требуется доступ на чтение почты, совместит эти параметры, создав следующий URL-адрес запроса:For example, an application that requires read access to mail would put all of those together to generate a request URL like the following:

Запрос кода авторизацииAuthorization code request

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<CLIENT ID>&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_type=code&scope=openid+Mail.Read

Пользователь увидит экран входа и название приложения. Если пользователь впервые запустил приложение, то после входа он увидит список разрешений, необходимых приложению, и предложение принять или отклонить их. Если он разрешит доступ, браузер будет перенаправлен на URI, указанный в первом запросе.The user will be presented with a sign in screen that displays the name of the app. Once they sign in, if it is their first time using the app, the user will be presented with a list of the app permissions the app requires and asked to allow or deny. Assuming they allow the required access, the browser will be redirected to the redirect URI specified in the initial request.

Запрос на перенаправление после успешного входаRedirect request after successful sign in

GET  HTTP/1.1 302 Found
Location: http://localhost/myapp/?code= AwABAAAA...cZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE

Значение параметра запроса code в URL-адресе — это код авторизации. Далее необходимо обменять код на маркер доступа.The value of the code query parameter in the URL is the authorization code. The next step is to exchange that code for an access token.

Получение маркера доступаGetting an access token

Чтобы получить маркер доступа, приложение помещает параметры, закодированные с использованием формы, в URL-адрес запроса маркера, который всегда будет таким:To get an access token, the app posts form-encoded parameters to the token request URL, which is always:

https://login.microsoftonline.com/common/oauth2/v2.0/token

Ниже перечислены параметры приложения.The app includes the following parameters.

  • client_id. Идентификатор клиента, создаваемый при регистрации приложения.client_id: the client ID generated by registering the app.
  • client_secret. Секрет клиента, создаваемый при регистрации приложения.client_secret: the client secret generated by registering the app.
  • code. Код авторизации, полученный на предыдущем этапе.code: the authorization code obtained in the prior step.
  • redirect_uri. Это значение должно совпадать со значением, используемым в запросе кода авторизации.redirect_uri: this value must be the same as the value used in the authorization code request.
  • grant_type. Тип предоставления, используемый приложением. Для потока предоставления авторизации всегда должно быть задано значение authorization_code.grant_type: the type of grant the app is using. For the Authorization Grant Flow, this should always be authorization_code.

Эти параметры шифруются с использованием типа контента application/x-www-form-urlencoded и отправляются на URL-адрес запроса маркера.These parameters are encoded to the application/x-www-form-urlencoded content type and sent to the token request URL.

Запрос маркера доступаAccess token request

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AwABAAAA...cZZ6IgAA&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&client_id=<CLIENT ID>&client_secret=<CLIENT SECRET>

В ответ Azure отправляет полезные данные JSON, которые включают маркер доступа.Azure responds with a JSON payload which includes the access token.

Ответ с маркером доступаAccess token response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "access_token":"eyJ0eXAi...b66LoPVA",
  "scope":"Mail.Read",
}

Маркер доступа находится в поле access_token полезных данных JSON. С помощью этого значения приложение задает заголовок Authorization при отправке вызовов REST к API.The access token is found in the access_token field of the JSON payload. The app uses this value to set the Authorization header when making REST calls to the API.

Вызов API почтыCalling the Mail API

После получения маркера доступа приложение готово к вызову API Почты. Справочник по API Почты содержит все необходимые сведения. Так как приложение получает сообщения, оно будет отправлять запрос HTTP GET на URL-адрес https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages. Так оно получит сообщения из папки "Входящие".Once the app has an access token, it's ready to call the Mail API. The Mail API Reference has all of the details. Since the app is retrieving messages, it will use an HTTP GET request to the https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages URL. This will retrieve messages from the inbox.

Параметры запросаRefining the request

Вы можете управлять запросами GET в приложении с помощью параметров запроса OData. Рекомендуем использовать эти параметры для ограничения числа возвращаемых результатов, а также полей, возвращаемых по каждому элементу. Рассмотрим эти действия на примере.Apps can control the behavior of GET requests by using OData query parameters. It is recommended that apps use these parameters to limit the number of results that are returned and to limit the fields that are returned for each item. Let's look at an example.

Представьте приложение, которое показывает сообщения в таблице. В ней отображаются только тема, отправитель, дата и время получения сообщения. Таблица содержит не более 25 строк: сообщения должны сортироваться по дате получения от новых к старым.Consider an app that displays messages in a table. The table only displays the subject, sender, and the date and time the message was received. The table displays a maximum of 25 rows, and should be sorted so that the most recently received message is at the top.

Для получения таких результатов приложение использует следующие параметры запроса:To achieve this, the app uses the following query parameters:

  • Параметр $select используется для указания полей subject, from и receivedDateTime.The $select parameter is used to specify only the subject, from, and receivedDateTime fields.
  • Параметр $top используется для указания не более 25 элементов.The $top parameter is used to specify a maximum of 25 items.
  • Параметр $orderby используется для сортировки результатов по полю receivedDateTime.The $orderby parameter is used to sort the results by the receivedDateTime field.

В результате мы получаем следующий запрос:This results in the following request.

Запрос сообщений из папки "Входящие" через API ПочтыMail API request for messages in the inbox

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
X-AnchorMailbox: jason@contoso.onmicrosoft.com

Ответ API ПочтыMail API Response

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. Обратите внимание, что необходимые для вызовов разрешения настраиваются во время регистрации приложения.Now that you've seen how to make calls to the Mail API, you can use the API reference to construct any other kinds of calls your app needs to make. However, bear in mind that your app needs to have the appropriate permissions configured on the app registration for the calls it makes.