API надстроек Outlook

Чтобы использовать API-интерфейсы в надстройке Outlook, необходимо указать расположение библиотеки Office.js, набор требований, схему и разрешения. В основном вы будете использовать Office API JavaScript, выставленные через объект почтовых ящиков.

Библиотека Office.js

Для взаимодействия с API надстроек Outlook необходимо использовать интерфейсы API JavaScript из библиотеки Office.js. Сеть CDN для библиотеки: https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. Надстройки, отправляемые в AppSource, должны ссылаться на библиотеку Office.js в этой сети CDN. Нельзя использовать локальную ссылку.

Добавьте ссылку на сеть CDN в теге <script>, вложенном в тег <head>, на веб-странице (HTML-, ASPX- или PHP-файле), где определяется пользовательский интерфейс надстройки.

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>

При добавлении новых API-интерфейсов не будет меняться URL-адрес Office.js. Мы укажем другую версию в URL-адресе, только если изменится поведение API.

Важно!

При разработке надстройки для Office клиентского приложения ссылайся на Office API JavaScript из раздела <head> страницы. Это гарантирует, что API полностью инициализируется раньше всех элементов body.

Наборы требований

Все API Outlook относятся к набору требований Mailbox. Существуют разные версии набора обязательных элементов Mailbox. Каждый новый набор API, который мы выпускаем, относится к более высокой версии набора. Не все клиенты Outlook поддерживают самый новый набор API при их выпуске, но если для клиента Outlook объявлена поддержка определенного набора обязательных элементов, то он поддерживает все API из этого набора.

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

Указание набора требований не означает, что надстройке будут доступны API-интерфейсы только из этой версии. Если в надстройке указан набор требований версии 1.1, но она выполняется в клиенте Outlook, поддерживающем версию 1.3, то надстройка может использовать API-интерфейсы версии 1.3. От набора требований зависит только то, в каких клиентах Outlook отображается надстройка.

Чтобы проверить доступность API-интерфейсов из набора требований, версия которого выше указанной в манифесте, вы можете использовать стандартный код JavaScript:

if (item.somePropertyOrFunction) {
   item.somePropertyOrFunction...  
}

Примечание

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

Укажите минимальный набор обязательных элементов API для вашего сценария, без которого функции надстройки не будут работать. Набор обязательных элементов указывается в элементе <Requirements> манифеста. Дополнительные сведения см. в статьях Манифесты надстроек Outlook и Общие сведения о наборах обязательных элементов API Outlook.

Элемент <Methods> не применяется к надстройкам Outlook, поэтому невозможно объявить поддержку определенных методов.

Разрешения

Для использования необходимых API-интерфейсов надстройке нужны соответствующие разрешения. Разрешения делятся на четыре уровня. Дополнительные сведения см. в статье Указание разрешений для доступа надстройки Outlook к почтовому ящику пользователя.


Уровень разрешений Описание
Ограниченный доступ Позволяет использовать сущности, но не регулярные выражения.
Чтение элемента Помимо возможностей уровня Ограниченный доступ, поддерживаются:
  • регулярные выражения;
  • доступ на чтение API надстроек Outlook;
  • получение свойств элемента и маркера обратного вызова.
Чтение и запись Помимо возможностей уровня Чтение элемента, поддерживаются:
  • полный доступ ко всем элементам API Outlook, кроме метода makeEwsRequestAsync;
  • задание свойств элемента.
Чтение и запись почтового ящика Помимо возможностей уровня Чтение и запись, поддерживаются:
  • создание, чтение и запись элементов и папок;
  • отправка папок;
  • вызов метода makeEwsRequestAsync.

Как правило, следует указывать минимальные разрешения, необходимые надстройке. Разрешения объявляются в элементе <Permissions> манифеста. Дополнительные сведения см. в статье Манифесты надстроек Outlook. Сведения о проблемах безопасности см. в Office конфиденциальности и безопасности надстройки.

Объект Mailbox

Outlook надстройки в основном используют API, выставленные через объект почтовых ящиков. Чтобы получить объекты и члены специально для использования в надстройках Outlook, такие как объект Item, используйте свойство mailbox объекта Context для получения доступа к объекту Mailbox, как показано в следующей строке кода.

// Access the Item object.
var item = Office.context.mailbox.item;

Кроме того, Outlook надстройки могут использовать следующие объекты.

  • Объект Office для инициализации.

  • Объект Context для получения доступа к контенту и отображения языковых свойств.

  • Объект RoamingSettings для сохранения пользовательских свойств, относящихся к надстройке Outlook, в почтовом ящике пользователя, в котором установлено приложение.

Сведения об использовании API Outlook JavaScript см. в Outlook надстройки.

См. также