Настройка надстройки Outlook для активации на основе событий

  • Статья

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

Примечание.

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

Сведения о том, как реализовать надстройку на основе событий, которая выполняется в Outlook на мобильных устройствах, см. в статье Реализация активации на основе событий в надстройках Outlook mobile.

Поддерживаемые события

В следующей таблице перечислены доступные в настоящее время события и поддерживаемые клиенты для каждого события. При возникновении события обработчик получает event объект, который может содержать сведения, относящиеся к типу события. Столбец Описание содержит ссылку на связанный объект, если применимо.

Каноническое имя
события и имя манифеста XML		 Унифицированный манифест для имени Microsoft 365 Описание Минимальный набор требований и поддерживаемые клиенты
OnNewMessageCompose newMessageComposeCreated При создании нового сообщения (включая ответить, ответить всем и пересылать), но не при редактировании, например, черновика. 1.10

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
— Android2
— iOS2
OnNewAppointmentOrganizer newAppointmentOrganizerCreated При создании новой встречи, но не при редактировании существующей. 1.10

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnMessageAttachmentsChanged messageAttachmentsChanged При добавлении или удалении вложений при создании сообщения.

Объект данных, зависящий от события: AttachmentsChangedEventArgs		 1.11

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnAppointmentAttachmentsChanged appointmentAttachmentsChanged При добавлении или удалении вложений при составлении встречи.

Объект данных, зависящий от события: AttachmentsChangedEventArgs		 1.11

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnMessageRecipientsChanged messageRecipientsChanged При добавлении или удалении получателей при создании сообщения.

Объект данных, зависящий от события: RecipientsChangedEventArgs		 1.11

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnAppointmentAttendeesChanged appointmentAttendeesChanged При добавлении или удалении участников во время создания встречи.

Объект данных, зависящий от события: RecipientsChangedEventArgs		 1.11

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnAppointmentTimeChanged appointmentTimeChanged При изменении даты и времени при составлении встречи.

Объект данных, зависящий от события: AppointmentTimeChangedEventArgs

Важно! При перетаскивании встречи в другой интервал даты и времени в календаре OnAppointmentTimeChanged событие не возникает. Это происходит только в том случае, если дата и время напрямую изменяются по сравнению с встречей.		 1.11

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnAppointmentRecurrenceChanged appointmentRecurrenceChanged При добавлении, изменении или удалении сведений о повторении при составлении встречи. Если дата и время изменены OnAppointmentTimeChanged , событие также возникает.

Объект данных, зависящий от события: RecurrenceChangedEventArgs		 1.11

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnInfoBarDismissClicked infoBarDismissClicked При отклонении уведомления при создании сообщения или элемента встречи. Будет уведомлена только надстройка, которая добавила уведомление.

Объект данных, зависящий от события: InfobarClickedEventArgs		 1.11

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnMessageSend messageSending При отправке элемента сообщения. Дополнительные сведения см. в пошаговом руководстве по интеллектуальным оповещениям. 1.12

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnAppointmentSend appointmentSending При отправке элемента встречи. Дополнительные сведения см. в статье Обработка событий OnMessageSend и OnAppointmentSend в надстройке Outlook с помощью смарт-оповещений. 1.12

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnMessageCompose messageComposeOpened При создании нового сообщения (включая ответить, ответить всем и пересылать) или редактировании черновика. 1.12

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnAppointmentOrganizer appointmentOrganizerOpened При создании новой встречи или редактировании существующей. 1.12

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnMessageFromChanged messageFromChanged При изменении учетной записи почты в поле От создаваемого сообщения. Дополнительные сведения см. в статье Автоматическое обновление подписи при переключении между учетными записями Exchange. 1.13

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnAppointmentFromChanged appointmentFromChanged При изменении учетной записи почты в поле организатора создаваемой встречи. Дополнительные сведения см. в статье Автоматическое обновление подписи при переключении между учетными записями Exchange. 1.13

- новый Outlook в Windows (предварительная версия)
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnSensitivityLabelChanged sensitivityLabelChanged При изменении метки конфиденциальности при составлении сообщения или встречи. Сведения об управлении меткой конфиденциальности почтового элемента см. в статье Управление меткой конфиденциальности сообщения или встречи в режиме создания.

Объект данных, зависящий от события: SensitivityLabelChangedEventArgs		 1.13

— Windows (классическаяверсия 1 и новая (предварительная версия))
— Веб-браузер
— Новый пользовательский интерфейс Mac
OnMessageReadWithCustomAttachment Недоступно При открытии сообщения, содержащего определенный тип вложения в режиме чтения. Предварительная версия3

— Windows1
OnMessageReadWithCustomHeader Недоступно При открытии сообщения, содержащего определенное имя заголовка в Интернете в режиме чтения. Предварительная версия3

— Windows1

Примечание.

1 Для работы надстроек на основе событий в Outlook в Windows требуется как минимум Windows 10 версии 1903 (сборка 18362) или Windows Server 2019 версии 1903.

2 Outlook на мобильных устройствах поддерживает API до набора обязательных почтовых ящиков 1.5. Однако теперь включена поддержка дополнительных API и функций, представленных в более поздних наборах требований, таких как OnNewMessageCompose событие. Дополнительные сведения см. в статье Реализация активации на основе событий в надстройках Outlook mobile.

3 Для предварительного OnMessageReadWithCustomAttachment просмотра событий и OnMessageReadWithCustomHeader необходимо установить Outlook в Windows версии 2312 (сборка 17110.10000) или более поздней. Затем присоединитесь к программе предварительной оценки Microsoft 365 и выберите параметр Канал бета-версии , чтобы получить доступ к бета-сборкам Office.

Устранение неполадок с надстройкой

При разработке надстройки на основе событий может потребоваться устранить неполадки, такие как не загружается надстройка или событие не возникает. Инструкции по устранению неполадок надстройки на основе событий см. в статье Устранение неполадок надстроек на основе событий и отчетов о спаме.

Развертывание для пользователей

Надстройки на основе событий ограничены только развертываниями, управляемыми администратором, даже если они получены из AppSource. Если пользователи получают надстройку из AppSource или магазина Office в приложении, они не смогут активировать функцию надстройки на основе событий. Дополнительные сведения о перечислении надстройки на основе событий в AppSource см. в статье Параметры описания AppSource для надстройки Outlook на основе событий.

Администратор развертывания выполняются путем отправки манифеста в Центр администрирования Microsoft 365. На портале администрирования разверните раздел Параметры в области навигации и выберите Интегрированные приложения. На странице Интегрированные приложения выберите действие Отправить пользовательские приложения .

Страница Интегрированные приложения на Центр администрирования Microsoft 365 с выделенным действием Отправить пользовательские приложения.

Важно!

Надстройки, использующие функцию смарт-оповещений , могут публиковаться в AppSource только в том случае, если свойству режима отправки манифеста задан параметр "пользователь с запросом " или параметром обратимого блока . Если свойство режима отправки надстройки имеет значение блокировать, оно может быть развернуто только администратором организации, так как оно не пройдет проверку AppSource.

Развертывание обновлений манифеста

Так как надстройки на основе событий развертываются администраторами, любое изменение манифеста требует согласия администратора через Центр администрирования Microsoft 365. Пока администратор не примет ваши изменения, пользователи в своей организации не будут использовать надстройку. Дополнительные сведения о процессе предоставления согласия администратора см. в разделе Администратор согласия на установку надстроек на основе событий.

Поведение и ограничения активации на основе событий

Ожидается, что обработчики событий запуска надстроек будут короткими, упрощенными и максимально неактивными. После активации время ожидания надстройки будет истекать в течение примерно 300 секунд, максимально допустимого времени для запуска надстроек на основе событий. Чтобы сообщить о том, что надстройка завершила обработку события запуска, связанный обработчик событий должен вызвать метод event.completed . (Обратите внимание, что код, включенный после инструкции event.completed , не гарантирует выполнение.) При каждом срабатывании события, которое обрабатывает надстройка, надстройка активируется повторно и запускает связанный обработчик событий, а время ожидания сбрасывается. Надстройка заканчивается после того, как истекает время ожидания, или пользователь закрывает окно создания или отправляет элемент.

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

Во всех поддерживаемых клиентах Outlook пользователь должен оставаться в текущем почтовом элементе, где была активирована надстройка, чтобы завершить выполнение. Переход от текущего элемента (например, переход к другому окну создания или вкладке) завершает операцию надстройки. Однако надстройка, активируемая в событии OnMessageSend , обрабатывает переключение элементов по-разному в зависимости от того, на каком клиенте Outlook она работает. Дополнительные сведения см. в разделе "Пользователь удаляется от текущего сообщения" статьи Обработка событий OnMessageSend и OnAppointmentSend в надстройке Outlook с помощью смарт-оповещений.

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

При разработке надстройки на основе событий для запуска в клиенте Outlook для Windows учитывайте следующее:

  • Импорт не поддерживается в файле JavaScript, в котором реализуется обработка активации на основе событий.

  • Надстройки не выполняют код, включенный в Office.onReady() и Office.initialize. Вместо этого рекомендуется добавить в обработчики событий любую логику запуска, например проверку версии Outlook пользователя.

  • Для активации на основе событий поддерживается только файл JavaScript, указанный в манифесте. Необходимо объединить код JavaScript для обработки событий в этот файл. Расположение указанного файла JavaScript в манифесте зависит от типа манифеста, используемого надстройкой.

    • XML-манифест: <переопределение> дочернего <элемента узла среды выполнения>
    • Унифицированный манифест для Microsoft 365 (предварительная версия): свойство script объекта code

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

Некоторые api Office.js, которые изменяют или изменяют пользовательский интерфейс, не допускаются из надстроек на основе событий. Ниже приведены заблокированные API.

Предварительный просмотр функций в обработчиках событий (Outlook для Windows)

Outlook в Windows включает локальную копию рабочей и бета-версий Office.js вместо загрузки из сети доставки содержимого (CDN). По умолчанию ссылается на локальную рабочую копию API. Чтобы сослаться на локальную бета-версию API, необходимо настроить реестр компьютера. Это позволит протестировать предварительные версии функций в обработчиках событий в Outlook в Windows.

  1. В реестре перейдите по адресу HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Если ключ не существует, создайте его.

  2. Создайте запись с именем EnableBetaAPIsInJavaScript и задайте для нее 1значение .

    Параметр реестра EnableBetaAPIsInJavaScript имеет значение 1.

Включение единого входа

Чтобы включить единый вход в надстройке на основе событий, необходимо добавить файл JavaScript в хорошо известный URI. Инструкции по настройке этого ресурса см. в статье Использование единого входа (SSO) или совместного доступа к ресурсам между источниками (CORS) в надстройке Outlook на основе событий или рассылки нежелательной почты.

Запрос внешних данных

Внешние данные можно запрашивать с помощью API , например Fetch , или с помощью XMLHttpRequest (XHR) — стандартного веб-API, который отправляет HTTP-запросы для взаимодействия с серверами.

Имейте в виду, что при использовании объектов XMLHttpRequest необходимо использовать дополнительные меры безопасности, требуя одну и ту же политику источника и CORS (общий доступ к ресурсам между источниками).

Примечание.

Полная поддержка CORS доступна в Outlook в Интернете, Mac и Windows (начиная с версии 2201, сборка 16.0.14813.10000).

Чтобы выполнять запросы CORS из надстройки на основе событий, необходимо добавить надстройку и ее файл JavaScript в хорошо известный URI. Инструкции по настройке этого ресурса см. в статье Использование единого входа (SSO) или совместного доступа к ресурсам между источниками (CORS) в надстройке Outlook на основе событий или рассылки нежелательной почты.

См. также