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

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

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

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

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

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

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

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

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

• Используйте конечную точку проверки подлинности Azure AD v2
• Используйте Azure Active Directory и OAuth

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

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

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

• портал регистрации приложений Майкрософт
• области авторизаций v2
• конечные точки проверки подлинности v2
  • https://login.microsoftonline.com/common/oauth2/v2.0/authorize
  • https://login.microsoftonline.com/common/oauth2/v2.0/token
• библиотеки ADAL v2

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

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

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

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

Регистрация и аутентификация с использованием 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.

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

Использование областей 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.

Поддерживаемые действия 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-адрес.

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

• Если вы разрабатываете приложения для Office 365 в Китае, вы должны продолжать использовать Конечные точки API Office 365 для Китая.

• Если вы создаете приложения для Outlook.com в Китае, попробуйте конечную точку проверки подлинности v2 и используйте следующую новую конечную точку REST Outlook: https://outlook.office.com/api/{version}/{user_context}.

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

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

• v1.0. Это самая ранняя версия, имеющая статус General Availability (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.

• beta. Эта версия находится в состоянии предварительной и не должна использоваться в рабочем коде. Пример 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:

• iOS
• Android
• JavaScript
• .NET

Они помогают управлять токенами проверки подлинности и упрощают код, необходимый для запроса и потребления данных в 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:

• Справка по API "Почта"
• Справка по API Календаря
• Справка по API Контакты
• API REST "Задачи"
• Справочные ресурсы для REST API «Почта», «Календарь», «Контакты» и «Задачи»
• Справка по API «Люди»
• Справка по API "Модули обработки данных"
• Справка по API "Расширенные свойства"
• Ссылка API REST push-уведомлений
• Справка относительно REST API потоковых уведомлений (предварительная версия)
• Справка по REST API "Фото пользователя"
• Пакетные запросы Outlook REST