Share via

Сопоставление строк в элементе Outlook как известных сущностей

  • Статья

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

Важно!

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

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

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

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

С помощью API JavaScript для Office можно получить эти строки, соответствующие определенным хорошо известным сущностям, для дальнейшей обработки. Известную сущность также можно указать в правиле в манифесте надстройки, чтобы программа Outlook смогла активировать надстройку, когда пользователь просматривает элемент, который содержит совпадения с этой сущностью. Затем вы можете извлечь и обработать совпадения с этой сущностью.

Примечание.

Функции надстроек Outlook, зависящие от правил активации, не поддерживаются, если надстройка использует унифицированный манифест для Microsoft 365.

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

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

Поддержка известных сущностей

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

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

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

Тип сущности Условия для распознавания Тип объекта
Address США адреса улиц. Например, "1234 Main Street, Redmond, WA 07722". В целом, чтобы адрес был распознан, он должен соответствовать структуре почтовых адресов в Соединенных Штатах с присутствием большинства элементов, таких как номер дома, название улицы, города, штата и почтовый индекс. Адрес может быть указан на одной или нескольких строках. Объект JavaScript String
Контакт Ссылки на сведения о человеке распознаются на естественном языке. Распознавание контакта зависит от контекста. Например, подпись в конце сообщения или имя человека появляются в непосредственной близости от таких сведений, как номер телефона, адрес, адрес эл. почты и URL-адрес. Объект Contact
EmailAddress SMTP-адреса электронной почты. Объект JavaScript String
MeetingSuggestion Ссылка на событие или собрание. Например, Exchange распознает следующий текст в качестве предложения собрания: "Давайте встретимся завтра на обед". Объект MeetingSuggestion
PhoneNumber США номера телефонов. Например, (235) 555–0110. ОбъектPhoneNumber
TaskSuggestion Предложения в сообщении электронной почты, являющиеся призывами к действию. Например, "Обновите электронную таблицу". Объект TaskSuggestion
Url Веб-адрес, который в явной форме указывает сетевое расположение и идентификатор веб-ресурса. Exchange Server не требует протокола доступа в веб-адресе и не распознает URL-адреса, внедренные в текст ссылки, как экземпляры сущностиUrl. Exchange Server могут соответствовать следующим примерам:www.youtube.com/user/officevideoshttps://www.youtube.com/user/officevideos Объект JavaScript String

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

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

Разрешения на извлечение сущностей

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

Указание ограниченного разрешения по умолчанию позволяет надстройке Addressизвлекать сущность , MeetingSuggestionили TaskSuggestion . Чтобы извлечь любую из других сущностей, укажите в манифесте разрешение на чтение, чтение и запись элемента или разрешение на чтение и запись почтового ящика .

В следующем примере запрашиваются разрешения на чтение элемента в манифесте.

<Permissions>ReadItem</Permissions>

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

Получение сущностей в надстройке

Если тема или текст элемента, которые просматривает пользователь, содержат строки, которые Exchange и Outlook могут распознать как известные сущности, то эти экземпляры будут доступны надстройке, даже если она была активирована без использования известных сущностей. С соответствующим разрешением getEntities можно использовать метод или getEntitiesByType для получения известных сущностей, присутствующих в текущем сообщении или встрече.

Метод getEntities возвращает массив объектов Entities , содержащий все хорошо известные сущности в элементе.

Если вас интересует определенный тип сущностей, используйте getEntitiesByTypeметод , который возвращает массив только из нужных сущностей. Перечисление EntityType представляет все типы известных сущностей, которые можно извлечь.

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

Как показано в примере на рисунке выше, чтобы получить адреса в элементе, получите доступ к массиву, возвращенному с помощью getEntities().addresses[]. Свойство Entities.addresses возвращает массив строк, которые Outlook распознает как почтовые адреса. Аналогичным образом свойство возвращает массив Contact объектов, Entities.contacts которые Outlook распознает как контактные данные. В таблице 1 приведен список типов объектов экземпляра каждой поддерживаемой сущности.

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

// Get the address entities from the item.
const entities = Office.context.mailbox.item.getEntities();
// Check to make sure that address entities are present.
if (null != entities && null != entities.addresses && undefined != entities.addresses) {
   //Addresses are present, so use them here.
}

Активация надстройки в зависимости от наличия сущности

Другой способ использовать известные сущности — активировать надстройку Outlook в зависимости от наличия одного или нескольких типов сущностей в теме или тексте элемента, который вы просматриваете в данный момент. Это можно сделать, указав ItemHasKnownEntity правило в манифесте надстройки. Простой тип EntityType представляет различные типы хорошо известных сущностей, поддерживаемых правилами ItemHasKnownEntity . После активации надстройки вы также сможете получить экземпляры таких сущностей для ваших целей, как описано в предыдущем разделе Получение сущностей в надстройке.

При необходимости можно применить регулярное выражение в ItemHasKnownEntity правиле, чтобы в дальнейшем фильтровать экземпляры сущности и активировать надстройку Outlook только для подмножества экземпляров сущности. Например, можно указать сущность адреса в сообщении, содержащем почтовый индекс штата Вашингтон, который начинается с "98". Чтобы применить фильтр к экземплярам сущностей, используйте RegExFilter атрибуты и FilterName в Rule элементе типа ItemHasKnownEntity .

Как и для других правил активации, можно указать несколько правил, составляющих коллекцию для вашей надстройки. В следующем примере операция "И" применяется к 2 правилам: правилу ItemIs и правилу ItemHasKnownEntity . Эта коллекция правил активирует надстройку, если текущий элемент является сообщением и Outlook распознает адрес в теме или тексте элемента.

<Rule xsi:type="RuleCollection" Mode="And">
   <Rule xsi:type="ItemIs" ItemType="Message" />
   <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>

В следующем примере текущий элемент используется getEntitiesByType для задания переменной addresses результатов предыдущей коллекции правил.

const addresses = Office.context.mailbox.item.getEntitiesByType(Office.MailboxEnums.EntityType.Address);

В следующем ItemHasKnownEntity примере правила надстройка активируется при наличии URL-адреса в теме или тексте текущего элемента, а URL-адрес содержит строку "youtube", независимо от регистра строки.

<Rule xsi:type="ItemHasKnownEntity" 
    EntityType="Url" 
    RegExFilter="youtube"
    FilterName="youtube"
    IgnoreCase="true"/>

В следующем примере текущий элемент используется getFilteredEntitiesByName(name) для задания переменной videos для получения массива результатов, соответствующих регулярному выражению в предыдущем правиле ItemHasKnownEntity .

const videos = Office.context.mailbox.item.getFilteredEntitiesByName(youtube);

Советы по использованию известных сущностей

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

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

  • Вы можете извлечь известные сущности только из первых 2000 символов в тексте элемента. Это ограничение размера помогает сбалансировать потребность в функциональности и производительности, чтобы Exchange Server и Outlook не завязывались при анализе и идентификации экземпляров известных сущностей в больших сообщениях и встречах. Обратите внимание, что это ограничение не зависит от того, указывает ли надстройка правило ItemHasKnownEntity . Если надстройка использует такое правило, обратите внимание на ограничение обработки правил для Outlook в Windows и на Mac далее в этом разделе.

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

  • Сущности MeetingSuggestion типа можно извлекать только из сообщений, но не из встреч.

  • Вы можете извлекать URL-адреса, явно указанные в теле элемента, но не URL-адреса, встроенные в текст гиперссылок в HTML-элементе. Вместо этого рекомендуется использовать ItemHasRegularExpressionMatch правило для получения явных и внедренных URL-адресов. Укажите BodyAsHTML в качестве свойства PropertyName и регулярное выражение, которое соответствует URL-адресам в качестве RegExValue.

  • Невозможно извлечь сущности из элементов в папке Отправленные .

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

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

  • Если надстройка работает в Outlook в Windows или на Mac, outlook применит ItemHasKnownEntity правило к первому мегабайту текста элемента, а не к остальной части текста.

  • Нельзя использовать ItemHasKnownEntity правило для активации надстройки для элементов в папке Отправленные .

См. также