将 Outlook 项中的字符串作为已知实体进行匹配

项目
02/07/2024

发送邮件或会议请求项之前，Exchange Server 将分析项目的内容、标识和标记类似于 Exchange 已知实体的主题和正文中的特定字符串，例如，电子邮件地址、电话号码和 URL。邮件和会议请求通过标有已知实体的 Outlook 收件箱中的 Exchange Server 传递。

重要

基于实体的上下文 Outlook 加载项将在 2024 年第 2 季度停用。停用此功能的工作将于 5 月开始，并持续到 6 月底。 6 月之后，上下文加载项将无法再检测邮件项目中的实体以对其执行任务。以下 API 也将停用。

为了帮助最大程度地减少潜在的中断，在基于实体的上下文加载项停用后，仍支持以下内容。

正在开发由联机会议加载项激活的 “加入 会议”按钮的替代实现。结束对基于实体的上下文加载项的支持后，联机会议加载项将自动转换为替代实现，以激活“ 加入会议 ”按钮。
基于实体的上下文加载项停用后，将继续支持正则表达式规则。建议更新上下文加载项，以使用正则表达式规则作为替代解决方案。有关如何实现这些规则的指南，请参阅使用正则表达式激活规则显示 Outlook 加载项。

有关详细信息，请参阅基于实体的上下文 Outlook 加载项的停用。

使用 Office JavaScript API，可以获取与特定已知实体匹配的这些字符串，以便进一步处理。还可以在外接程序清单中的某个规则中指定已知实体，以便当用户查看某个包含该实体匹配项的项目时，Outlook 可以激活外接程序。然后您可以提取实体匹配项并对其执行操作。

注意

当外接程序使用 Microsoft 365 统一清单时，不支持依赖于激活规则的 Outlook 外接程序功能， (预览版) 。

能够识别或从所选的邮件或约会中提取此类实例是很方便的。例如，可以构建一个反向电话查找服务，作为 Outlook 外接程序。该外接程序可从项目主题或正文中提取类似于电话号码的字符串，执行反向搜索并显示每个电话号码的注册所有者。

本主题将介绍这些已知实体，显示基于已知实体的激活规则示例，以及如何独立使用激活规则中的实体提取实体匹配项。

支持已知实体

在发件人发送项目之后和 Exchange 将项目传递给收件人之前，Exchange Server 将标记邮件或会议请求项目中的已知实体。因此，只标记在 Exchange 中传输的项目，用户查看此类项目时，Outlook 可以根据这些标记激活外接程序。反之，用户撰写项目或查看“已发送邮件”文件夹中的项目时，由于项目还没有进行传输，Outlook 无法根据已知实体激活外接程序。

同样，无法提取正在撰写的项目中和“已发送邮件”文件夹中的已知实体，因为这些项目尚未进行传输和标记。有关支持激活的项目类型的其他信息，请参阅 Outlook 外接程序的激活规则。

下表列出 Exchange Server 和 Outlook 支持和识别的实体（因而称作"已知实体"）和每个实体实例的对象类型。将字符串作为某一实体的自然语言识别基于某学习模型，该模型根据大量数据进行训练。因此，该识别具有不确定性。请参阅使用已知实体的提示来了解有关识别条件的详细信息。

实体类型	识别条件	对象类型
地址	美国街道地址。例如，“1234 Main Street， Redmond， WA 07722”。通常，对于要识别的地址，它应遵循美国邮政地址的结构，包含街道编号、街道名称、城市、州和邮政编码等大部分元素。地址可写在一行或多行中。	JavaScript String 对象
Contact	对于在自然语言中识别的个人信息的引用。联系人的识别取决于上下文。例如，邮件末尾的签名或在以下信息附近出现的人员姓名：电话号码、地址、电子邮件地址和 URL。	Contact 对象
EmailAddress	SMTP 电子邮件地址。	JavaScript `String` 对象
MeetingSuggestion	对事件或会议的引用。例如，Exchange 会将以下文本识别为会议建议：“让我们明天共进午餐。	MeetingSuggestion 对象
PhoneNumber	美国电话号码。例如， (235) 555-0110。	PhoneNumber 对象
TaskSuggestion	电子邮件中的可操作语句。例如，“请更新电子表格”。	TaskSuggestion 对象
Url	明确指定了 Web 资源的网络位置和标识符的 Web 地址。 Exchange Server不需要 Web 地址中的访问协议，并且不会将链接文本中嵌入的 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 返回一个实体对象数组，其中包含项中的所有已知实体。

如果对特定类型的实体感兴趣，请使用方法， getEntitiesByType该方法仅返回所需实体的数组。 EntityType 枚举表示可以提取的所有已知实体类型。

调用 getEntities后，可以使用对象的相应属性 Entities 来获取实体类型的实例数组。根据实体的类型，数组中的实例可以只是字符串，也可以映射到特定对象。

作为前面的图中的示例，若要获取该项目中的地址，请访问由 getEntities().addresses[] 返回的数组。属性 Entities.addresses 返回 Outlook 识别为邮政地址的字符串数组。同样，属性 Entities.contacts 返回 Outlook 识别为联系人信息的对象数组 Contact 。表 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"开头的华盛顿州邮政编码的街道地址实体指定筛选器。若要对实体实例应用筛选器，请在 ItemHasKnownEntity 类型的元素中使用 RegExFilterRule 和 FilterName 属性。

类似于其他激活规则，您可以指定多个规则，为外接程序形成一个规则集合。以下示例对 2 个规则应用“AND”操作：一个 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 规则，以下内容就适用。

仅当字符串为英文形式时，您才可以提取已知实体字符串。
您可以从项目正文的前 2,000 个字符中提取已知实体，但不能超过此限制。此大小限制有助于平衡对功能和性能的需求，以便不会通过分析和识别大型邮件和约会中已知实体的实例来使Exchange Server和 Outlook 陷入困境。请注意，此限制与加载项是否指定 ItemHasKnownEntity 规则无关。如果加载项确实使用此类规则，另请注意本节后面的 Windows 版和 Mac 版 Outlook 的规则处理限制。
您可以从约会（由邮箱所有者之外的人员组织的会议）中提取实体。无法从不是会议的日历项目或由邮箱所有者组织的会议中提取实体。
只能从邮件中提取类型的 MeetingSuggestion 实体，而不能从约会中提取实体。
您可以提取项目正文中明确存在的 URL，但无法提取 HTML 项目正文中内嵌在超链接文本中的 URL。请考虑改用 ItemHasRegularExpressionMatch 规则来获取显式和嵌入 URL。将指定 BodyAsHTML 为 PropertyName，并将与 URL 匹配的正则表达式指定为 RegExValue。
无法从 “已发送邮件 ”文件夹中的项目中提取实体。

此外，如果使用 ItemHasKnownEntity 规则，则以下规则适用，并且可能会影响你希望激活加载项的方案。

使用 ItemHasKnownEntity 规则时，无论清单中指定的默认区域设置如何，都要求 Outlook 仅以英语匹配实体字符串。
当加载项在 Outlook on Windows 或 Mac 中运行时，预期 Outlook 会将规则应用于 ItemHasKnownEntity 项目正文的第一兆字节，而不是应用于超过该限制的正文的其余部分。
不能使用 ItemHasKnownEntity 规则为 “已发送邮件 ”文件夹中的项目激活加载项。