Ограничения на активацию и API JavaScript для надстроек Outlook

Статья
02/29/2024

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

Примечание.

Также необходимо убедиться, что надстройка работает в пределах определенных ограничений на использование ресурсов среды выполнения. Дополнительные сведения см. в разделе Среды выполнения в надстройках Office.

Где активируются надстройки

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

Ограничения для API JavaScript

Каждый клиент Outlook применяет определенные ограничения в объектной модели JavaScript, как описано в следующей таблице.

Функция	Ограничение	Связанный API	Описание
Настраиваемые свойства	2500 символов	Объект CustomProperties Метод Item.loadCustomPropertiesAsync	Ограничение для всех настраиваемых свойств элемента встречи или сообщения. Все клиенты Outlook возвращают ошибку, если общий размер всех настраиваемых свойств надстройки превышает это ограничение.
Перемещаемые параметры	32 КБ символов	Объект RoamingSettings Свойство Context.roamingSettings	Ограничение для всех параметров перемещения надстройки. Все клиенты Outlook возвращают ошибку, если параметры превышают это ограничение.
Заголовки Интернета	256 КБ на сообщение в Exchange Online Ограничение на размер заголовка определяется администраторами организации в локальной среде Exchange	Метод InternetHeaders.setAsync	Общий размер заголовков, которые можно применить к сообщению.
Извлечение известных сущностей	2000 символов	Метод Item.getEntities Метод Item.getEntitiesByType Метод Item.getFilteredEntitiesByName	Ограничение для Exchange Server для извлечения известных сущностей в основном тексте элемента. Exchange Server игнорирует сущности сверх этого предела. Обратите внимание, что это ограничение не зависит от того, использует ли надстройка `ItemHasKnownEntity` правило.
Веб-службы Exchange	5 МБ символов в Outlook в Интернете, в Windows (начиная с версии 2303 (сборка 16225.10000)), в Mac (начиная с версии 16.73 (23042601)) и в новом Outlook для Windows (предварительная версия) 1 МБ символов в более ранних версиях Outlook в Windows и на Mac	Метод Mailbox.makeEwsRequestAsync	Ограничение для запроса или ответа на `Mailbox.makeEwsRequestAsync` вызов.
Элемент с несколькими выборами	100 сообщений	Метод Mailbox.getSelectedItemsAsync	Максимальное количество выбранных сообщений, для которых может активироваться надстройка Outlook.
Recipients	Отличается в разных клиентах Outlook	Свойство Item.requiredAttendees Свойство Item.optionalAttendees свойство Item.to свойство Item.cc Метод Recipients.addAsync Метод Recipients.getAsync Метод Recipients.setAsync	Ограничение для получателей, указанных в каждом свойстве или методе. Сведения об ограничениях получателей для определенного клиента Outlook см. в документации по API для свойства или метода.
Отображаемое имя	255 символов	Свойство EmailAddressDetails.displayName Объект Recipients Свойство Item.requiredAttendees Свойство Item.optionalAttendees свойство Item.to свойство Item.cc	Ограничение длины отображаемого имени в сообщении или встрече.
Установка темы	255 символов	DisplayedSubject.setAsync (предварительная версия) Метод Mailbox.displayNewAppointmentForm Метод Subject.setAsync	Ограничение для темы в форме новой встречи или для настройки темы встречи или сообщения.
Установка места проведения	255 символов	Метод Location.setAsync	Ограничение для установки расположении встречи или приглашения на собрание.
Текст в форме новой встречи	32 КБ символов	Метод Mailbox.displayNewAppointmentForm	Ограничение текста в форме новой встречи.
Отображение текста существующего элемента	32 КБ символов	Метод Mailbox.displayAppointmentForm Метод Mailbox.displayMessageForm	Для Outlook в Интернете, мобильных устройств и нового Outlook в Windows (предварительная версия) — ограничение текста в существующей форме встречи или сообщения.
Настройка текста	1 МБ символов	Метод Body.prependAsync Body.setAsync Метод Body.setSelectedDataAsync DisplayedBody.setAsync (предварительная версия)	Ограничение для установки текста элемента встречи или сообщения.
Установка сигнатуры	30 000 символов	Метод Body.setSignatureAsync	Ограничение длины подписи в встрече или сообщении.
Число вложений	499 файлов в Outlook в Интернете, на мобильных устройствах и в новом Outlook в Windows (предварительная версия)	Метод Item.addFileAttachmentAsync	Ограничение количества файлов, которые можно вложить в отправляемый элемент. Outlook в Интернете и на мобильных устройствах, а также новые Outlook в Windows (предварительная версия) обычно ограничивают подключение до 499 файлов с помощью пользовательского интерфейса и `addFileAttachmentAsync` метода. Outlook в Windows и mac не ограничивает количество файловых вложений. Однако все клиенты Outlook соблюдают ограничение размера вложений, определяемое Exchange Server пользователя (см. строку "Размер вложений" в этой таблице).
Размер вложений	В зависимости от Exchange Server	Метод Item.addFileAttachmentAsync	Существует ограничение на размер всех вложений для почтового элемента, которое администратор может настроить в Exchange Server почтового ящика пользователя. Для Outlook в Windows и на Mac это ограничивает количество вложений для элемента. Для Outlook в Интернете и на мобильных устройствах, а также нового Outlook в Windows (предварительная версия) меньшее из двух ограничений ( количество вложений и размер всех вложений) ограничивает фактические вложения для элемента.
Имя файла вложения	255 символов	Метод Item.addFileAttachmentAsync	Ограничение длины имени файла вложения, добавляемого в элемент.
URI вложения	2048 символов	Метод Item.addFileAttachmentAsync Метод Item.addFileAttachmentFromBase64Async	Ограничение URI имени файла, добавляемого в элемент как вложение.
Строка вложения в кодировке Base64	27 892 122 символа (около 25 МБ)	Метод Item.addFileAttachmentFromBase64Async	Ограничение строки в кодировке Base64, добавляемой в качестве вложения к элементу.
Идентификатор вложения	100 символов	Метод Item.addItemAttachmentAsync Метод Item.removeAttachmentAsync	Ограничение длины идентификатора вложения, добавляемого в элемент или удаляемого из него.
Асинхронные вызовы	3 вызова	Метод Item.addFileAttachmentAsync Метод Item.addItemAttachmentAsync Метод Item.removeAttachmentAsync Метод Body.getTypeAsync Метод Body.prependAsync Метод Body.setSelectedDataAsync Метод CustomProperties.saveAsync Метод Item.LoadCustomPropertiesAsync Метод Location.getAsync Метод Location.setAsync Метод Mailbox.getCallbackTokenAsync Метод Mailbox.getUserIdentityTokenAsync Метод Mailbox.makeEwsRequestAsync Метод Recipients.addAsync Метод Recipients.getAsync Метод Recipients.setAsync Метод RoamingSettings.saveAsync Метод Subject.getAsync Метод Subject.setAsync Метод Time.getAsync Метод Time.setAsync	Для Outlook в Интернете и на мобильных устройствах, а также нового Outlook в Windows (предварительная версия): ограничение числа одновременных асинхронных вызовов в любой момент времени, так как браузеры разрешают только ограниченное количество асинхронных вызовов к серверам.
Добавление при отправке	5000 символов	Метод Body.appendOnSendAsync	Ограничение содержимого, добавляемого в сообщение или текст встречи при отправке.
Prepend-on-send	5000 символов	Метод Body.prependOnSendAsync	Ограничение содержимого, которое добавляется к сообщению или тексту встречи при отправке.

Ограничения правил активации для контекстных надстроек Outlook

Важно!

Контекстные надстройки Outlook на основе сущностей будут прекращены во 2-м квартале 2024 г. Работа по прекращению использования этой функции начнется в мае и продолжится до конца июня. После июня контекстные надстройки больше не смогут обнаруживать сущности в почтовых элементах для выполнения задач над ними. Следующие API также будут прекращены.

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

Разрабатывается альтернативная реализация кнопки "Присоединиться к собранию ", которая активируется надстройками собраний по сети. После завершения поддержки контекстных надстроек на основе сущностей надстройки собраний по сети автоматически переходят на альтернативную реализацию для активации кнопки Присоединиться к собранию .
Правила регулярных выражений будут поддерживаться после прекращения использования контекстных надстроек на основе сущностей. Мы рекомендуем обновить контекстную надстройку, чтобы использовать правила регулярных выражений в качестве альтернативного решения. Инструкции по реализации этих правил см. в статье Использование правил активации регулярных выражений для отображения надстройки Outlook.

Дополнительные сведения см. в разделе Прекращение использования контекстных надстроек Outlook на основе сущностей.

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

Размер манифеста не должен превышать 256 КБ. Вы не сможете установить надстройку Outlook для почтового ящика Exchange, если превысите это ограничение.

Примечание.

Функции надстроек Outlook, зависящие от правил активации, не поддерживаются, если надстройка использует унифицированный манифест для Microsoft 365.
Задавайте не более 15 правил активации для надстройки. Вы не сможете установить надстройку, если превысите это ограничение.
Если в Outlook в Windows и на Mac используется правило ItemHasKnownEntity в тексте выбранного элемента, оно должно применяться только к первым 1 МБ текста, а не к остальной части текста сверх этого предела. Ваша надстройка не активируется, если совпадения существуют только после первого МБ основного текста. Если вы ожидаете, что это будет вероятным сценарием, измените условия активации.
Если вы используете регулярные выражения в ItemHasKnownEntityправилах Или ItemHasRegularExpressionMatch , учитывайте следующие ограничения и рекомендации, которые обычно применяются к любому приложению Outlook и описанные в таблицах последующих разделов, которые отличаются в зависимости от приложения.
- Укажите только пять регулярных выражений в правилах активации в надстройке. Вы не сможете установить надстройку, если превысите это ограничение.
- Укажите регулярные выражения таким образом, чтобы ожидаемые результаты возвращались вызовом getRegExMatches метода в течение первых 50 совпадений.
- Важно! Текст выделяется на основе строк, которые являются результатом сопоставления регулярного выражения. Однако выделенные вхождения могут не точно соответствовать тому, что должно быть результатом фактических утверждений регулярных выражений, таких как отрицательный взгляд вперед (?!text), просмотр за спиной (?<=text)и отрицательный просмотр позади (?<!text). Например, если вы используете регулярное выражение under(?!score) "Like under, under score, and подчеркивание", строка "under" выделяется для всех вхождений, а не только для первых двух.

Различия в поддержке регулярных выражений

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

Outlook в Интернете, на мобильных устройствах и в новом клиенте Windows (предварительная версия)	Outlook в Windows и на Mac
Клиенты используют вычисление регулярных выражений, которое является частью JavaScript. Он предоставляется браузером и поддерживает надмножество ECMAScript 5.	Клиенты используют обработчик регулярных выражений C++, предоставляемый как часть стандартной библиотеки шаблонов Visual Studio. Этот обработчик выполняет компиляцию в соответствии со стандартами ECMAScript 5.
Необходимо тщательно протестировать каждый регулярный экземпляр на каждом клиенте Outlook. Если регулярное выражение возвращает другие результаты, перепишите его.	Из-за различных обработчиков регулярных выражений регулярное выражение, включающее пользовательский класс символов на основе предопределенных классов символов, может возвращать разные результаты в Outlook в Windows и на Mac и в Outlook в Интернете, на мобильных устройствах и в новом Outlook для Windows (предварительная версия). Например, регулярное выражение `[\s\S]{0,100}` соответствует любому числу (от 0 до 100) отдельных символов, которые являются пробелами или не пробелами. Этот регулярный результат возвращает разные результаты в зависимости от клиента Outlook. В качестве обходного решения следует переписать регулярное выражение как `(\s\\|\S){0,100}`. Эта регулярность соответствует любому числу (от 0 до 100) пробелов или небелых пробелов. Необходимо тщательно протестировать каждый регулярный экземпляр на каждом клиенте Outlook. Если регулярное выражение возвращает другие результаты, перепишите его.
Параметры мониторинга ресурсов и реестра, поддерживаемые в Outlook в Windows и на Mac, не поддерживаются в Outlook в Интернете, на мобильных устройствах и в новом Outlook для Windows (предварительная версия). Однако надстройки с регулярными выражениями, для которых требуется слишком много времени оценки в Outlook в Windows и на Mac, отключены для одного и того же почтового ящика во всех клиентах Outlook.	По умолчанию оценка всех регулярных выражений для надстройки ограничена одной секундой. Превышение этого предела приводит к повторной вычислении до трех раз. За пределы переоценки Outlook в Windows и на Mac запрещает запуск надстройки для одного и того же почтового ящика в любом из клиентов Outlook. Администраторы могут переопределить эти ограничения оценки с помощью `OutlookActivationAlertThreshold` разделов реестра и `OutlookActivationManagerRetryLimit` .

Ограничения размеров основного текста элемента, используемого для оценки

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

	Outlook в Интернете и в новом клиенте Windows (предварительная версия)	Outlook в классическом клиенте Windows и на Mac	Outlook на мобильных устройствах
Конструктивные параметры	Любые поддерживаемые устройства, кроме смартфонов Android, iPad и iPhone.	Любое поддерживаемого устройства.	Смартфоны Android, iPad или iPhone.
Основной текст элемента в виде обычного текста	Активирует надстройку только в том случае, если текст < содержит 500 000 символов.	Регулярное выражение применяется к первому мегабайту данных в основном тексте. К остальной части основного текста свыше этого ограничения регулярное выражение не применяется.	Активирует надстройку только в том случае, если текст < содержит 16 000 символов.
Основной текст элемента в формате HTML	Активирует надстройку только в том случае, если текст < содержит 500 000 символов.	Применяет регулярное выражение к первым 512 КБ данных основного текста, но не к остальной части текста сверх этого предела. (Фактическое количество символов зависит от кодировки, которая может варьироваться от 1 до 4 байт на символ.)	Регулярное выражение применяется к первым 64 000 знаков (включая знаки HTML-тегов). К остальной части основного текста свыше этого ограничения регулярное выражение не применяется.

Ограничения возвращаемых соответствий

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

	Outlook в Интернете, на мобильных устройствах и в новом клиенте Windows (предварительная версия)	Outlook в классическом клиенте Windows и на Mac
Порядок возвращаемых соответствий	Предположим, `getRegExMatches` что метод возвращает разные совпадения для одного и того же регулярного выражения, применяемого к одному и тому же почтовому элементу в Outlook в Windows и Mac, а также в Outlook в Интернете, на мобильных устройствах и в новом Outlook для Windows (предварительная версия).	Предположим, `getRegExMatches` что метод возвращает разные совпадения для одного и того же регулярного выражения, применяемого к одному и тому же почтовому элементу в Outlook в Windows и Mac, а также в Outlook в Интернете, на мобильных устройствах и в новом Outlook для Windows (предварительная версия).
Основной текст элемента в виде обычного текста	`getRegExMatches` возвращает все совпадения длиной до 3072 символов (3 КБ) для не более 50 совпадений.	Метод `getRegExMatches` возвращает все совпадения длиной до 1536 (1,5 КБ) для не более 50 совпадений. Примечание. `getRegExMatches` Не возвращает совпадения в определенном порядке в возвращаемом массиве. Как правило, предположим, что порядок совпадений для одного регулярного выражения, применяемого к одному и тому же почтовому элементу в Outlook в Windows и на Mac, отличается от порядка совпадений в Outlook в Интернете, на мобильных устройствах и в новом Outlook в Windows (предварительная версия).
Основной текст элемента в формате HTML	`getRegExMatches` возвращает все совпадения длиной до 3072 символов (3 КБ) для не более 50 совпадений.	`getRegExMatches` возвращает все совпадения длиной до 3072 символов (3 КБ) для не более 50 совпадений. Примечание. `getRegExMatches` Не возвращает совпадения в определенном порядке в возвращаемом массиве. Как правило, предположим, что порядок совпадений для одного регулярного выражения, применяемого к одному и тому же почтовому элементу в Outlook в Windows и на Mac, отличается от порядка совпадений в Outlook в Интернете, на мобильных устройствах и в новом Outlook в Windows (предварительная версия).