Использование REST API Outlook (бета-версия)

  • Статья

Область применения: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Примечание

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

API REST Outlook включает следующие подмножества, позволяющие получать доступ к данным почтовых ящиков пользователей в Office 365, Hotmail.com, Live.com, MSN.com, Outlook.com и Passport.com.

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

Подмножество API Доступные версии
Пакетная обработка нескольких вызовов API версия 2.0, бета-версия
API календаря версия 2.0, версия 1.0, бета-версия
API Контактов версия 2.0, версия 1.0, бета-версия
API модулей обработки данных версия 2.0, бета-версия
API расширенных свойств версия 2.0, бета-версия
API Почты версия 2.0, версия 1.0, бета-версия
API push-уведомлений версия 2.0, бета-версия
API потоковых уведомлений (предварительная версия) бета
API Люди бета
API задач версия 2.0, бета-версия
API фотографий пользователя версия 2.0, бета-версия

Примечание

В остальной части этой статьи описывается общая информация, применимая ко всем подмножествам API REST Outlook. Для простоты ссылок в остальной части статьи "Outlook.com" включает учетные записи в доменах Hotmail.com, Live.com, MSN.com, Outlook.com и Passport.com.

Зарегистрируйте и подтвердите подлинность своей программы

Чтобы использовать API REST Outlook для доступа к данным почтового ящика пользователя, ваше приложение должно обрабатывать регистрацию и авторизацию пользователя:

  1. Сначала зарегистрируйте свое приложение, чтобы получить доступ к API REST Outlook. Затем вы можете реализовать вызовы API в своем приложении.

  2. Во время выполнения получите авторизацию от пользователя и выполните запросы API REST для доступа к почтовому ящику пользователя.

В настоящее время существует два подхода к регистрации приложений и авторизации пользователей:

Конечная точка проверки подлинности Azure AD v2

Конечная точка проверки подлинности Azure AD v2 упрощает создание приложения, которое работает как с корпоративными, так и с личными учетными записями Microsoft. Это позволяет пользователям рабочих, школьных и персональных учетных записей входить в систему нажатием одной кнопки.

Эта конвергентная модель программирования является новейшим подходом, который включает в себя следующее:

Такой подход дает вам возможность беспрепятственной регистрации приложений и авторизации пользователей, чтобы получить соответствующие токены для доступа к данным почтовых ящиков пользователей в Office 365 и/или Outlook.com. Если вы разрабатываете приложение для Outlook.com, вы должны использовать этот подход.

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

Эта конвергентная модель программирования состоит из нескольких компонентов, поэтому, если вы используете один компонент, вы должны использовать и другие.

Чтобы узнать больше, см. примеры для начала работы, а также Проверка подлинности API Office 365 и Outlook.com с использованием конечной точки проверки подлинности v2.

Важно!

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

Регистрация и аутентификация с использованием Azure AD и OAuth

Это более ранний подход для доступа к данным почтового ящика только для Office 365. Если вы планируете получать доступ к данным на Outlook.com или создавать новое приложение для Office 365, используйте вместо этого Конечную точку проверки подлинности v2.

В настоящее время для доступа к данным почтового ящика Office 365 вы можете продолжать регистрировать приложение в Azure AD, как и раньше, указав разрешения в соответствующей области, которые требуются вашему приложению. Во время выполнения ваше приложение может продолжать использовать Azure AD и OAuth для проверки подлинности запросов приложений. Вы можете найти подробную информацию в Концепции проверки подлинности приложений Office 365. Вы должны запланировать путь обновления.

При таком подходе вы можете получить доступ к API REST Outlook, вызвав его непосредственно в своих приложениях Office 365 или используя клиентские библиотеки Office 365.

Путь обновления

Конечная точка проверки подлинности v2 была переведена из статуса предварительного просмотра в статус общедоступной (GA) для разработчиков Outlook и Outlook.com.

Если у вас есть рабочее приложение, которое обращается к данным почтового ящика Office 365, или если вы создаете новое приложение для Office 365 или Outlook.com, планируйте использовать конечную точку проверки подлинности v2 вместе с новейшей конечной точкой Outlook (https://outlook.office.com/, см. ниже), чтобы получить возможность написания всего одного набора кода как для пользователей Office 365 в организациях, так и для пользователей Outlook.com.

Если у вас есть рабочее приложение, которое использует API Windows Live для доступа к данным почтового ящика Outlook.com, вы должны перезаписать приложение, чтобы использовать конечную точку проверки подлинности v2 и API REST Outlook. Поскольку API Windows Live не рекомендуется для пользователей Outlook.com, а у пользователей Outlook.com почтовые ящики включены для работы с API REST Outlook, такие пользователи получат сообщения об ошибках HTTP 404 при попытке запуска таких приложений API Windows Live.

С другой стороны, API REST Outlook открывает перед вами новые возможности—вы можете выбрать один из распространенных языков, таких как Node, Python, Swift, Java и т.д., написать приложение один раз и охватить как пользователей Outlook.com, так и Office 365 в Интернете и в устройствах на базе iOS, Android или Windows.

Примечание

Если вы хотите, чтобы ваше рабочее приложение продолжало доступ только к данным почтового ящика Outlook.com, вы можете продолжать использовать те же области Windows Live для доступа к большинству API REST Outlook. Более подробную информацию см. в разделе Использование областей Windows Live и API REST Outlook для доступа к данным почтового ящика Outlook.com.

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

https://outlook.office.com/api/{version}/{user_context}

Следующая конечная точка REST Outlook будет продолжать работать некоторое время только для данных почтового ящика Office 365:

https://outlook.office365.com/api/{version}/{user_context}

Узнайте больше о поддерживаемых действиях REST, конечных точках, а также версиях ниже.

Важно!

  • Базовая авторизация больше не поддерживается конечной точкой API REST Outlook https://outlook.office.com. Используйте конечную точку проверки подлинности v2 или Azure AD для авторизации и проверки подлинности для приложения, которое использует новую конечную точку API REST Outlook.
  • Для оптимальной производительности при использовании новой конечной точки REST Outlook добавляйте x-AnchorMailbox заголовок для каждого запроса и устанавливайте его на адрес электронной почты пользователя. Пример: x-AnchorMailbox:john@contoso.com
  • Поскольку включение почтовых ящиков на Outlook.com для API REST Outlook происходит в течение определенного периода времени, для имеющейся у вас учетной записи Outlook.com может потребоваться некоторое время для активации. Чтобы протестировать доступ приложения к данным в почтовых ящиках Outlook.com, которые уже включены, вы можете запросить новую предварительную включенную учетную запись разработчика на Outlook.com, направив соответствующий запрос по электронной почте outlookdev@microsoft.com.
  • Если ваше приложение обращается к данным почтового ящика Outlook.com, оно должно обрабатывать сценарии, в которых почтовый ящик пользователя еще не включен для API REST Outlook. В таких ситуациях, при выполнении запроса REST, вы получаете сообщение об ошибке, подобное этому:
    • Ошибка HTTP: 404
    • Код ошибки: MailboxNotEnabledForRESTAPI или MailboxNotSupportedForRESTAPI
    • Сообщение об ошибке: "API REST пока не поддерживается для этого почтового ящика.
  • Для образцов кода, которые используют конечную точку проверки подлинности v2, см. dev.outlook.com.

Использование областей Windows Live и API REST Outlook для доступа к данным почтового ящика Outlook.com

Если ваше рабочее приложение для Outlook.com использует области Windows Live, и вы не собираетесь выбирать в качестве целевых данные почтового ящика Office 365, вы можете продолжать использовать эти области Windows Live с большей частью API REST Outlook. В приведенной ниже таблице показано, как области Windows Live сопоставляются с областями API REST Outlook. Обратите внимание: нет прямого отображения области Windows Live для Mail.Read; ваше приложение может использовать wl.imap для доступа к этим API REST Outlook, которые требуют Mail.Read.

Области Windows Live Области API REST Outlook
wl.basic User.Read, Contacts.Read
wl.calendars Calendars.Read
wl.calendars_update Calendars.ReadWrite
wl.contacts_create Contacts.ReadWrite
wl.contacts_calendars Calendars.Read
wl.emails User.Read
wl.events_create Calendars.ReadWrite
wl.imap Mail.ReadWrite, Mail.Send

Поддерживаемые действия REST и конечные точки

Чтобы взаимодействовать с API REST Outlook, вы отправляете HTTP-запросы, которые используют поддерживаемый метод: GET, POST, PATCH или DELETE. Органы запроса POST и PATCH и ответы сервера отправляются в полезные данные JSON.

Имена ресурсов в URL-адресах и путях, а также параметры запросов нечувствительны к регистру. Однако присваиваемые значения, идентификаторы объектов и другие кодированные значения base64 чувствительны к регистру.

Все запросы API REST Outlook используют следующий новый корневой URL-формат:

https://outlook.office.com/api/{version}/{user_context}

При соответствующей авторизации пользователя API REST в этом корневом URL-адресе предоставляет доступ к данным почтового ящика в Office 365 и Outlook.com. Остальная часть этой статьи описывает API REST в этой конечной точке.

Если у вас есть код, использующий уже предварительно существующей корневой URL-адрес https://outlook.office365.com/api/{version}/{user_context}, этот код будет продолжать работать некоторое время для Office 365, но вы должны запланировать переход на новый корневой URL-адрес.

Важно!

Для обеспечения оптимальной производительности при выполнении запроса REST с использованием нового корневого URL-адреса добавьте x-AnchorMailbox заголовок и задайте ему значение адреса электронной почты пользователя. Кроме того, обработайте случай, когда почтовый ящик пользователя на Outlook.com еще не включен для API REST Outlook; проверьте на наличие кодов ошибок MailboxNotEnabledForRESTAPI и MailboxNotSupportedForRESTAPI. Подробнее – здесь.

Примечания для разработчиков в Китае

Поддерживаемые версии API

{version} представляет версию API REST Outlook в указанном корневом URL-адресе. Вы можете указать одно из следующих значений:

  • v1.0. Это самая ранняя версия, имеющая статус Общедоступности (GA), которая может использоваться в производственном коде. Пример URL: http://outlook.office.com/api/v1.0/me/events.

  • v2.0. Эта версия также находится в статуса GA и может использоваться в рабочем коде. Пример URL: http://outlook.office.com/api/v2.0/me/events. Эта версия включает изменения, которые могут нарушить v1.0, и дополнительные наборы API, которые были доработаны и переведены со статуса предварительной версии до статуса GA.

  • бета-версия. Эта версия находится в состоянии предварительной и не должна использоваться в рабочем коде. Пример URL: http://outlook.office.com/api/beta/me/events. Эта версия включает новейший API в GA, а также дополнительные наборы API, которые находятся в режиме предварительной версии, и которые могут измениться до завершения.

Большинство операций REST в API REST Outlook поддерживаются и ведут себя так же, как описано в перечисленных выше версиях.

Целевой пользователь

За исключением API REST фото пользователя, {user_context} является пользователем, находящимся в настоящее время в системе, поскольку запросы API REST Outlook всегда выполняются от имени текущего пользователя.

Для API REST фото пользователя, {user_context} может быть вошедшим в систему пользователем или пользователем, указанным идентификатором пользователя.

Независимо от набора API REST Outlook вы можете указать {user_context} в запросах REST одним из следующих способов:

  • С помощью me ярлыка: /api/{version}/me. Корневой URL-адрес становится https://outlook.office.com/api/{version}/me.

  • С помощью users/{upn} формата для передачи UPN или прокси-адреса зарегистрированного пользователя, например: /api/beta/users/sadie@contoso.com. В этом примере корневой URL-адрес становится https://outlook.office.com/api/beta/users/sadie@contoso.com.

  • С помощью users/{AAD_userId@AAD_tenandId} формата, использующего идентификатор пользователя и идентификатор арендатора в Azure Active Directory. Например, users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77. Корневой URL-адрес становится https://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77.

Использование - это вопрос предпочтения.

В ответах сервера_пользовательский контекст идентифицируется_в этом формате: users/{AAD_userId@AAD_tenandId}.

Доступ к элементу в коллекции

API REST Outlook поддерживает два способа указания элемента в коллекции сущностей. Они оцениваются одинаково, поэтому использование - вопрос предпочтения.

  • В сегменте URL после коллекции, например: /api/{version}/me/events/AAMkAGI3...

  • В скобках, например, в виде строки в кавычках: /api/{version}/me/events('AAMkAGI3...')

Используйте клиентскую библиотеку для доступа к API REST Outlook

Клиентские библиотеки API Office 365 упрощают взаимодействие с API REST:

Они помогают управлять токенами проверки подлинности и упрощают код, необходимый для запроса и потребления данных в Office 365.

Выключение конечной точки более ранней предварительной версии

Если вы уже используете https://outlook.office.com/api или https://outlook.office365.com/api в качестве корневого URL
для доступа к API REST Outlook такое устаревание не касается вас. Продолжайте читать, если вы все еще используете конечную точку более ранней предварительной версииhttps://outlook.office365.com/ews/odata.

API REST Outlook перешел от своей первоначальной предварительной версии к версии v1.0 общей доступности в октябре 2014 года. Чтобы завершить этот переход, мы закрыли старую конечную точку предварительной версии https://outlook.office365.com/ews/odata15 октября 2015 г..

Все приложения и службы, использующие прежнюю конечную точку, должны были https://outlook.office365.com/ews/odata перейти на https://outlook.office.com/api/v1.0 до 15 октября 2015 г. v1.0 — минимальная конечная точка общедоступности (GA), на которую следовало перейти до наступления этой даты.

В качестве альтернативы, вы можете использовать предпочтительную конечную точку GA v2.0 (https://outlook.office.com/api/v2.0) или конечную точку предварительной версии (https://outlook.office.com/api/beta), чтобы попробовать новейшие API в статусе предварительной версии. Имейте в виду, что, в общем случае, API в статусе предварительной версии может измениться до завершения. Если вы используете их, будьте готовы проверить функции в своем приложении и внести соответствующие изменения. Когда API в предварительной версии будут завершены, вы также сможете получить доступ к этим улучшениям в конечной точке GA.

Дальнейшие действия

Перейдите к использованию API REST Outlook: