Наборы обязательных элементов API JavaScript для Outlook

Надстройки Outlook объявляют, какие версии API им требуются, в манифесте. Разметка зависит от того, используете ли вы формат манифеста только для надстроек или единый манифест для Microsoft 365.

Версия API задается свойством extensions.requirements.capabilities. Задайте для свойства "capabilities.name" значение "Mailbox", а для свойства "capabilities.minVersion" — минимальный набор требований к API, поддерживающий сценарии надстройки.

Например, в следующем фрагменте манифеста указан минимальный набор обязательных элементов 1.1.

"extensions": [
{
  "requirements": {
    "capabilities": [
      {
        "name": "Mailbox", "minVersion": "1.1"
      }
    ]
  },
  ...
}

Все API Outlook относятся к наборуMailbox требований. У набора требований Mailbox есть версии, а каждый новый выпускаемый набор API-интерфейсов приведен в наборе более поздней версии. Не все клиенты Outlook поддерживают новейший набор API, но если клиент Outlook заявляет о поддержке набора требований, он обычно поддерживает все API в этом наборе требований (проверьте документацию по определенному API или функции на наличие каких-либо исключений).

Минимальный набор требований, указанный в манифесте, определяет, какие клиенты Outlook могут загружать надстройку. Если клиент Outlook не поддерживает хотя бы указанную версию, надстройка не загружается. Например, если задать требуемую версию 1.3, надстройка будет отображаться только в клиентах Outlook, поддерживающих версию 1.3 или более позднюю.

Примечание.

Хотя Outlook для Android и iOS поддерживают до набора требований 1.5, теперь ваша мобильная надстройка может реализовать некоторые API из более поздних наборов требований. Дополнительные сведения о том, какие API поддерживаются в Outlook Mobile, см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.

Использование API из более поздних наборов требований

Установка набора требований не ограничивает доступные API, которые может использовать надстройка. Например, если в надстройке указан набор требований "Почтовый ящик 1.1", но она выполняется в клиенте Outlook, который поддерживает "Почтовый ящик 1.3", надстройка может использовать API из набора требований "Почтовый ящик 1.3".

Чтобы использовать более новые API, разработчики могут проверить, поддерживает ли конкретное приложение набор обязательных элементов, выполнив следующее.

if (Office.context.requirements.isSetSupported('Mailbox', '1.3')) {
  // Perform actions.
}
else {
  // Provide alternate flow/logic.
}

Кроме того, разработчики могут проверить наличие более новых API с помощью стандартных методов JavaScript.

if (item.somePropertyOrMethod !== undefined) {
  // Use item.somePropertyOrMethod.
  item.somePropertyOrMethod;
}

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

Выберите набор минимальных требований

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

Наборы обязательных элементов, поддерживаемые серверами Exchange и клиентами Outlook

В этом разделе указан диапазон наборов обязательных элементов, поддерживаемых сервером Exchange и клиентами Outlook. Сведения о требованиях к серверу и клиенту для запуска надстроек Outlook см. в статье Требования надстроек Outlook.

Важно!

Если целевой сервер Exchange и клиент Outlook поддерживают разные наборы обязательных элементов, возможно, вы ограничены применением более ранней версии набора обязательных элементов. Например, если надстройка работает в Outlook 2019 для Windows (максимальный набор требований: 1.6) и Exchange 2016 (максимальный набор требований: 1.5), ваша надстройка может быть ограничена набором требований 1.5.

Поддержка сервера Exchange

В следующей таблице перечислены серверы Exchange и поддерживаемые ими наборы требований к почтовым ящикам. Чтобы надстройка отображалась в Outlook, размещенном в определенной среде Exchange, эта среда должна поддерживать версию, указанную в манифесте надстройки в качестве минимального требования.

Продукт Основная версия Exchange Поддерживаемые наборы обязательных элементов API
Exchange Online Последняя сборка 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16
IdentityAPI 1.31
Локальная среда Exchange Subscription Edition (SE) 1.1, 1.2, 1.3, 1.4, 1.5
2019 1.1, 1.2, 1.3, 1.4, 1.5
2016 1.1, 1.2, 1.3, 1.4, 1.5

1 Чтобы потребовать набор API удостоверений 1.3 в коде надстройки Outlook, выполните проверку, поддерживается ли он с помощью вызова isSetSupported('IdentityAPI', '1.3'). Его объявление в манифесте надстройки Outlook не поддерживается. Также можно определить, поддерживается ли API, проверив, не undefined ли он. Подробнее см. в статье Использование API из наборов требования более поздних версий.

Даже если надстройка реализует функции из более поздних наборов требований, не поддерживаемых в локальной среде Exchange, ее все равно можно добавить в клиент Outlook, если минимальный набор требований, указанный в ее манифесте, соответствует минимальным требованиям, поддерживаемым локальной службой Exchange. Однако реализованная функция работает только в том случае, если клиент Outlook, в котором установлена надстройка, поддерживает минимальный набор требований, необходимый для функции. Например, надстройка для подписи, в манифесте которой в манифесте указано 1.5, будет установлена и загружена в локальной среде Exchange 2019. Однако его вызов Body.setSignatureAsync, который был введен в наборе требований 1.10, будет выполняться только в том случае, если клиент Outlook, на котором установлена надстройка, поддерживает версию 1.10.

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

Поддержка клиентов Outlook

Надстройки поддерживаются в Outlook на следующих платформах.

Платформа Основная версия Office или Outlook Поддерживаемые наборы обязательных элементов API
Веб-браузер1 2 современный пользовательский интерфейс Outlook при подключении к
Exchange Online: подписка, Outlook.com		 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16
DevicePermissionService 1.1
DialogAPI 1.1
DialogAPI 1.2
DialogOrigin 1.1
IdentityAPI 1.33
NestedAppAuth 1.1
классический пользовательский интерфейс Outlook при подключении к
Локальная среда Exchange		 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
Windows новый пользовательский интерфейс Outlook с подпиской на Microsoft 365 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16
DevicePermissionService 1.1
DialogAPI 1.1
DialogAPI 1.2
DialogOrigin 1.1
IdentityAPI 1.33
NestedAppAuth 1.1
классический пользовательский интерфейс Outlook с подпиской на Microsoft 3654 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16
DialogAPI 1.1
DialogAPI 1.2
DialogOrigin 1.1
IdentityAPI 1.33
NestedAppAuth 1.1
OpenBrowserWindowApi 1.1
розничная торговля с бессрочной лицензией Outlook 2021 и более поздних версий (классический пользовательский интерфейс Outlook)4 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16
DialogAPI 1.1
DialogAPI 1.2
DialogOrigin 1.1
IdentityAPI 1.33
NestedAppAuth 1.1
OpenBrowserWindowApi 1.1
бессрочная лицензия с корпоративной лицензией/LTSC Outlook 2024 (классический пользовательский интерфейс Outlook) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14
DialogAPI 1.1
DialogAPI 1.2
DialogOrigin 1.1
IdentityAPI 1.33
NestedAppAuth 1.1
OpenBrowserWindowApi 1.1
бессрочная лицензия с корпоративной лицензией или LTSC Outlook 2021 (классический пользовательский интерфейс Outlook) 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9
DialogAPI 1.1
DialogAPI 1.2
DialogOrigin 1.1
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
Mac новый пользовательский интерфейс5 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14
DialogAPI 1.1
DialogAPI 1.2
DialogOrigin 1.1
IdentityAPI 1.33
NestedAppAuth 1.1
OpenBrowserWindowApi 1.1
классический пользовательский интерфейс 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
DialogAPI 1.1
DialogAPI 1.26
DialogOrigin 1.1
IdentityAPI 1.33
NestedAppAuth 1.1
OpenBrowserWindowApi 1.1
Android1 7 подписка 1.1, 1.2, 1.3, 1.4, 1.5
NestedAppAuth 1.1
iOS1 7 подписка 1.1, 1.2, 1.3, 1.4, 1.5
NestedAppAuth 1.1

1 Надстройки не поддерживаются в Outlook для Android, iOS и современном мобильном Интернете с локальными учетными записями Exchange. Некоторые устройства с iOS по-прежнему поддерживают надстройки при использовании локальных учетных записей Exchange с классическим приложением Outlook в Интернете. Сведения о поддерживаемых устройствах см. в разделе Требования к запуску надстроек для Office.

2 Надстройки не работают в современном Outlook в Интернете на iPhone и смартфонах Android. Сведения о поддерживаемых устройствах см. в разделе Требования к запуску надстроек для Office.

3 Чтобы потребовать набор API удостоверений 1.3 в коде надстройки Outlook, выполните проверку, поддерживается ли он с помощью вызова isSetSupported('IdentityAPI', '1.3'). Его объявление в манифесте надстройки Outlook не поддерживается. Также можно определить, поддерживается ли API, проверив, не undefined ли он. Подробнее см. в статье Использование API из наборов требования более поздних версий.

4 Сведения о минимальных поддерживаемых версиях для последних наборов требований в классической версии Outlook для Windows с подпиской Microsoft 365 или розничной бессрочной лицензией см. в статье "Поддержка версий для наборов требований в классической версии Outlook для Windows".

5 Поддержка нового пользовательского интерфейса Mac доступна в Outlook версии 16.38.506. Дополнительные сведения см. в разделе Поддержка надстроек в Outlook в новом интерфейсе Mac.

6 Хотя классическая версия Outlook для Mac не поддерживает набор требований к почтовому ящику 1.9, она поддерживает набор требований DialogApi 1.2. Сведения о минимальной поддерживаемой версии и сборке см. в разделе Наборы требований API диалогов.

7 В настоящее время существуют дополнительные соображения при проектировании и реализации надстроек для мобильных клиентов. Дополнительные сведения см. в статье "Соображения по использованию кода" при добавлении поддержки команд надстроек в Outlook на мобильных устройствах. Хотя Outlook для Android и iOS поддерживают до набора требований 1.5, теперь ваша мобильная надстройка может реализовать некоторые API из более поздних наборов требований. Дополнительные сведения о том, какие API поддерживаются в Outlook Mobile, см. в статье API JavaScript Outlook, поддерживаемые Outlook на мобильных устройствах.

Совет

Классическую и современную версии Outlook в веб-браузере можно различить по внешнему виду панели инструментов почтового ящика.

современная версия

Современная панель инструментов Outlook.

классическая версия

Классическая панель инструментов Outlook.

Поддержка версий для наборов требований в классической версии Outlook для Windows

В следующей таблице перечислены поддерживаемые версии для более поздних наборов требований к почтовому ящику в классическом Outlook для Windows с подпиской на Microsoft 365 или бессрочной лицензией на розничную продажу.

Набор обязательных элементов Версия
1.8 Версия 1910 (сборка 12130.20272)
1.9 Версия 2008 (сборка 13127.20296)
1.10 Версия 2104 (сборка 13929.20296)
1.11 Версия 2110 (сборка 14527.20226)
1.12 Версия 2206 (сборка 15330.20196)
1.13 Версия 2304 (сборка 16327.20248)
1.14 Версия 2404 (сборка 17530.15000)
1.15 Версия 2412 (сборка 18324.20172)
1.16 Версия 2602 (сборка 19725.20126)

Дополнительные сведения о версии клиента см. на странице журнала обновлений Microsoft 365 или Office 2024 , а также о том, как узнать версию клиента Office и канал обновления.

Примечание.

В Outlook каждый канал обновления получает обновления с разной скоростью. Чтобы убедиться, что ваш канал поддерживает определенную версию или сборку, см. статью Журнал обновлений Приложения Microsoft 365. Сравнение различных каналов обновления см. в разделе Обзор каналов обновления для Приложения Microsoft 365.

Справочник по рабочей библиотеке API JavaScript Office

Чтобы использовать API в любом из нумерованных наборов обязательных элементов, следует ссылаться на рабочую библиотеку в сети доставки содержимого (CDN) Office.js. Дополнительные сведения об использовании предварительных API см. в статье Тестирование предварительных API.

API для предварительного тестирования

Новые API JavaScript для Outlook сначала выпускаются в "предварительной версии", а затем становятся частью определенного нумерованного набора обязательных элементов после выполнения достаточного тестирования и получения отзывов пользователей. Чтобы отправить отзыв о предварительной версии API, используйте способ обратной связи, представленный в конце веб-страницы с описанием API.

Примечание.

Предварительные версии API могут быть изменены и не предназначены для использования в рабочей среде.

Дополнительные сведения о предварительных версиях интерфейсов API см. в статье Предварительная версия набора обязательных элементов API для Outlook.

  • Last updated on