Сравнение конечных точек REST API Outlook и Microsoft Graph

Статья
04/08/2023

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

Примечание.

API Outlook REST устарели.

Конечные точки REST Outlook будут полностью списаны в марте 2024 г. Миграция существующих приложений для использования Microsoft Graph. Сюда не входит аудитория маркеров OAuth2, как описано в разделе Проверка подлинности подключения IMAP, POP или SMTP с помощью OAuth.

Какую конечную точку выбрать?

Используйте Microsoft Graph, Outlook REST версии 2.0 находится на пути к списанию. Конечная точка Microsoft Graph позволяет получать доступ к Outlook и многим другим службам и функциям, включая другие службы Office 365, Enterprise Mobility + безопасности и Windows 10. Конечная точка Microsoft Graph позволяют приложению получить маркер доступа для обращения к данным Outlook и других ресурсов без необходимости создавать несколько запросов на получение маркера.

Функциональные различия

На текущий момент некоторые функции доступны только в конечной точке Outlook или представлены в Microsoft Graph только в бета-версии.

Примечание.

Мы постоянно работаем над тем, чтобы включить в Microsoft Graph все функции, доступные в настоящее время в конечной точке Outlook. Периодически проверяйте этот список, поскольку он обновляется.

Функция	Разница между конечными точками
Задачи Outlook	Доступ к задачам пользователей в Microsoft Graph предоставлен через API To Do
Расширенные уведомления	Интерфейс API Outlook позволяет разработчикам запрашивать включение определенных полей в полезные данные уведомления с помощью параметра `$select`. В настоящее время Microsoft Graph поддерживает эту функцию только в бета-версии конечной точки, планируя выпустить ее до версии 1.0 в ближайшее время.
Потоковые уведомления	API Outlook поддерживает потоковые уведомления в предварительном варианте для конечной точки бета-версии. Microsoft Graph не поддерживает эту функцию и не входит в дорожную карту.

Перемещение из конечной точки Outlook в Microsoft Graph

API-интерфейсы конечных точек Microsoft Graph и Outlook очень похожи. Однако есть некоторые отличия, которые следует учитывать, особенно в том случае, если вы переходите на Microsoft Graph или используете обе конечные точки в одном приложении.

Версии API

В случае API Microsoft Graph доступны версии v1.0 и beta, тогда как в случае Outlook — версии v1.0, v2.0 и beta. Версия v1.0 Microsoft Graph соответствует версии v2.0 Outlook, а версия beta Microsoft Graph — версии beta Outlook.

Области OAuth

Несмотря на то что конечные точки Microsoft Graph и Outlook используют маркеры, предоставленные Azure AD, и используются одинаковые разрешения, способ запроса этих разрешений приложением немного отличается для каждой конечной точки.

Конечная точка OAuth2 Azure версии 2

Приложения, использующие конечную точку Azure AD версии 2.0 для OAuth2, требуют области разрешений в параметре scope в запросе на проверку подлинности или на получение маркера.

Для Microsoft Graph приложения указывают разрешения с помощью префикса https://graph.microsoft.com/. Например, приложение может запросить разрешение Mail.Read путем включения https://graph.microsoft.com/Mail.Read в параметр scope.
Для конечной точки Outlook приложения указывают разрешения с помощью префикса https://outlook.office.com/. Например, приложение может запросить разрешение Mail.Read путем включения https://outlook.office.com/Mail.Read в параметр scope.

Примечание.

Если домен не включен в область, предполагается использование Microsoft Graph.

Маркеры, выпущенные для одной конечной точки, не подходят для другой. Кроме того, в одном запросе нельзя объединять разрешения для одной конечной точки с разрешениями для другой.

Конечная точка Azure AD версии 2.0 поддерживает только поток учетных данных клиента для конечной точки Microsoft Graph. Приложения, требующие применения маркера только для приложения с конечной точкой Outlook, должны использовать конечную точку Azure AD версии 1.0.

Конечная точка OAuth2 Azure версии 1

Приложения, использующие конечную точку Azure AD версии 1.0, указывают необходимые разрешения во время регистрации приложения на портале Azure.

Для Microsoft Graph выберите API Microsoft Graph при добавлении необходимых разрешений.
Для конечной точки Outlook выберите API Exchange Online в Office 365 при добавлении необходимых разрешений.

Имена свойств для ресурсов

Ресурсы в microsoft Graph и Outlook в значительной степени совпадают. Однако для этих двух конечных точек по-разному используется регистр в именах свойств. Microsoft Graph предусматривает применение для имен свойств "верблюжьего" стиля (camelCase), тогда как в случае Outlook все части пишутся с прописной буквы (PascalCase). При выполнении преобразования между этими двумя конечными точками необходимо просто изменить регистр. Имена измененных свойств указываются в таблице ниже.

Например, ресурс message в Microsoft Graph определяет свойства как subject, from и receivedDateTime. В конечной точке Outlook эти свойства будут именоваться Subject, From и ReceivedDateTime.

Изменяемые имена свойств

Следующие имена свойств различны для Microsoft Graph и Outlook.

Тип ресурса	Свойство Microsoft Graph	Свойство Outlook
`contact`	`mobilePhone`	`MobilePhone1`

Отслеживание изменений (синхронизация)

Обе конечные точки поддерживают запрашивание изменений коллекций, касающихся состояния синхронизации. Хотя функциональные возможности одинаковы, методы слегка разнятся.

В конечной точке Microsoft Graph изменения запрашиваются с использованием разностных запросов. Это реализовано как функция delta в коллекции.

В конечной точке Outlook изменения запрашиваются путем добавления заголовка в обычные запросы к коллекции ресурсов.

Совмещение

Обе конечные точки поддерживают совмещение до 20 отдельных запросов в одном HTTP-запросе.

При совмещении в Microsoft Graph преобразуются несколько запросов API в тело JSON с типом контента application/json.

Совмещение конечных точек Outlook поддерживает не только формат JSON, но и формат составного тела с типом контента multipart/mixed.

Пример: извлечение сообщения

Рассмотрим простой пример. В этом сценарии веб-приложение запрашивает список сообщений в пользовательской папке "Входящие".

Microsoft Graph

Сначала выполняется вход пользователя для авторизации приложения. Так как приложение использует область Mail.Read Microsoft Graph, URL-адрес авторизации выглядит следующим образом:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+Mail.Read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

Как только у приложения появляется маркер доступа, оно отправляет следующий запрос:

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject,from,receivedDateTime,isRead
Accept: application/json
Authorization: Bearer <token>

Сервер возвращает отклик:

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('b63d5fb9-4f43-44c4-8f9d-fd0727842876')/mailFolders('inbox')/messages(subject,from,receivedDateTime,isRead)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject%2cfrom%2creceivedDateTime%2cisRead&$skip=1",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "id": "AAMkAGI2...",
      "receivedDateTime": "2015-11-03T03:21:04Z",
      "subject": "Scrum",
      "isRead": false,
      "from": {
        "emailAddress": {
          "name": "user0TestUser",
          "address": "user0@contoso.com"
        }
      }
    }
  ]
}

Outlook

Сначала выполняется вход пользователя для авторизации приложения. Так как приложение использует область https://outlook.office.com/Mail.Read Outlook, URL-адрес авторизации выглядит следующим образом:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+https%3A%2F%2Foutlook.office.com%2Fmail.read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

Как только у приложения появляется маркер доступа, оно отправляет следующий запрос:

GET https://outlook.office.com/api/v2.0/me/mailfolders/inbox/messages?$top=1&$select=Subject,From,ReceivedDateTime,IsRead
Accept: application/json
Authorization: Bearer <token>

Сервер возвращает отклик:

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "@odata.nextLink": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "Id": "AAMkAGI2...",
      "ReceivedDateTime": "2015-11-03T03:21:04Z",
      "Subject": "Scrum",
      "IsRead": false,
      "From": {
        "EmailAddress": {
          "Name": "user0TestUser",
          "Address": "user0@contoso.com"
        }
      }
    }
  ]
}

Сравнение конечных точек REST API Outlook и Microsoft Graph

Какую конечную точку выбрать?

Функциональные различия

Перемещение из конечной точки Outlook в Microsoft Graph

Версии API

Области OAuth

Конечная точка OAuth2 Azure версии 2

Конечная точка OAuth2 Azure версии 1

Имена свойств для ресурсов

Изменяемые имена свойств

Отслеживание изменений (синхронизация)

Совмещение

Пример: извлечение сообщения

Microsoft Graph

Outlook

Дополнительные ресурсы