Erkennen bestimmter Zeichenfolgen in einem Outlook-Element als bekannte EntitätenMatch strings in an Outlook item as well-known entities

Vor dem Senden einer Nachricht oder Besprechungsanfrage analysiert Exchange Server den Inhalt des Elements und identifiziert und stempelt bestimmte Zeichenfolgen im Betreff und im Textkörper, die Entitäten ähneln, die Exchange bekannt sind, z. B. E-Mail-Adressen, Telefonnummern und URLs. Nachrichten und Besprechungsanfragen werden von Exchange Server in einem Outlook-Posteingang bereitgestellt, wobei bekannte Identitäten gestempelt werden.Before sending a message or meeting request item, Exchange Server parses the contents of the item, identifies and stamps certain strings in the subject and body that resemble entities well-known to Exchange, for example, email addresses, phone numbers, and URLs. Messages and meeting requests are delivered by Exchange Server in an Outlook Inbox with well-known entities stamped.

Mithilfe der JavaScript-API für Office können Sie diese Zeichenfolgen, die bekannten Entitäten entsprechen, zur weiteren Verarbeitung abrufen. Sie können im Add-in-Manifest mithilfe einer Regel auch eine bekannte Entität festlegen, sodass Outlook Ihr Add-In aktivieren kann, wenn der Benutzer ein Element anzeigt, das Übereinstimmungen mit dieser Entität enthält. Sie können Übereinstimmungen mit der Entität extrahieren und Aktionen daran ausführen.Using the JavaScript API for Office, you can get these strings that match specific well-known entities for further processing. You can also specify a well-known entity in a rule in the add-in manifest so that Outlook can activate your add-in when the user is viewing an item that contains matches for that entity. You can then extract and take action on matches for the entity.

Die Fähigkeit, solche Instanzen in einer ausgewählten Nachricht oder einem Termin zu identifizieren oder sie zu extrahieren, ist praktisch. Beispielsweise können Sie so einen umgekehrten Telefonsuchdienst als Outlook-add-in erstellen. Das Add-In kann Zeichenfolgen im Betreff oder Text extrahieren, die einer Telefonnummer ähneln, und ein reverses Lookup ausführen, um den registrierten Besitzer jeder Telefonnummer anzuzeigen.Being able to identify or extract such instances from a selected message or appointment is convenient. For example, you can build a reverse phone look-up service as an Outlook add-in. The add-in can extract strings in the item subject or body that resemble a phone number, do a reverse lookup, and display the registered owner of each phone number.

In diesem Thema werden diese bekannten Entitäten vorgestellt und Beispiele für Aktivierungsregeln gegeben, die auf bekannten Entitäten basieren. Außerdem erfahren Sie, wie Entitäten mit und ohne derartige Aktivierungsregeln extrahiert werden.This topic introduces these well-known entities, shows examples of activation rules based on well-known entities, and how to extract entity matches independently of having used entities in activation rules.

Unterstützung für bekannte EntitätenSupport for well-known entities

Exchange Server stempelt bekannte Entitäten in einer Nachricht oder Besprechungsanfrage, nachdem der Absender das Element gesendet hat und bevor Exchange das Element an den Empfänger liefert. Daher werden nur Elemente gestempelt, die von Exchange transportiert wurden, und Outlook kann Add-Ins auf Basis dieser Stempel aktivieren, wenn der Benutzer diese Elemente aufruft. Wenn der Benutzer allerdings ein Element verfasst oder ein Element im Ordner „Gesendete Objekte" aufruft, kann Outlook Add-Ins nicht auf Basis bekannter Entitäten aktivieren, da das Element nicht von Exchange transportiert wurde.Exchange Server stamps well-known entities in a message or meeting request item after the sender sends the item and before Exchange delivers the item to the recipient. Therefore, only items that have gone through transport in Exchange are stamped, and Outlook can activate add-ins based on these stamps when the user is viewing such items. On the contrary, when the user is composing an item or viewing an item that is in the Sent Items folder, because the item has not gone through transport, Outlook cannot activate add-ins based on well-known entities.

Entsprechend können Sie bekannte Entitäten nicht in Elementen extrahieren, die verfasst werden oder sich im Ordner „Gesendete Objekte“ befinden, da diese Elemente nicht von Exchange transportiert und nicht gestempelt wurden. Weitere Informationen zu den Arten von Elementen, die Aktivierung unterstützen, finden Sie unter Aktivierungsregeln für Outlook-Add-Ins.Similarly, you cannot extract well-known entities in items that are being composed or in the Sent Items folder, as these items have not gone through transport and are not stamped. For additional information about the kinds of items that support activation, see Activation rules for Outlook add-ins.

In der folgenden Liste werden die Entitäten aufgeführt, die Exchange Server und Outlook unterstützen und erkennen (daher der Name "bekannte Entitäten") sowie auch den Objekttyp der Instanz einer jeden Entität. Die natürliche Spracherkennung einer Zeichenfolge einer dieser Entitäten basiert auf einem Lernmodell, das mit einer großen Datenmenge trainiert wurde. Deshalb ist die Erkennung nicht deterministisch. Weitere Informationen zu den Erkennungsbedingungen finden Sie unter Tipps zur Verwendung bekannter Entitäten.The following table lists the entities that Exchange Server and Outlook support and recognize (hence the name "well-known entities"), and the object type of an instance of each entity. The natural language recognition of a string as one of these entities is based on a learning model that has been trained on a large amount of data. Therefore, the recognition is non-deterministic. See Tips for using well-known entities for more information about conditions for recognition.

Tabelle 1. Unterstützte Entitäten und deren TypenTable 1. Supported entities and their types

EntitätstypEntity type Bedingung für die ErkennungConditions for recognition ObjekttypObject type
AdresseAddress US-Anschrift, wie beispielsweise: 1234 Main Street, Redmond, WA 07722. Im Allgemeinen gilt für die Erkennung einer Adresse, dass sie sich an die Struktur einer US-Postanschrift halten sollte und die meisten Elemente wie Hausnummer, Straßenname, Ort, Bundesstaat und PLZ vorhanden sein sollten. Die Adresse kann in einer oder mehreren Zeilen angegeben werden.United States street addresses; for example: 1234 Main Street, Redmond, WA 07722. Generally, for an address to be recognized, it should follow the structure of a United States postal address, with most of the elements of a street number, street name, city, state, and zip code present. The address can be specified in one or multiple lines. JavaScript-Objekt des Typs StringJavaScript String object
KontaktContact Ein Verweis auf die Informationen einer Person wie sie in natürlicher Sprache erkannt wurde. Die Erkennung eines Kontakts hängt vom Kontext ab. Beispielsweise eine Signatur am Ende einer Nachricht oder den Namen einer Person, wenn er in der Nähe einiger die folgenden Informationen angezeigt wird: eine Telefonnummer, Adresse, e-Mail-Adresse und URL.A reference to a person's information as recognized in natural language. The recognition of a contact depends on the context. For example, a signature at the end of a message, or a person's name appearing in the vicinity of some of the following information: a phone number, address, email address, and URL. Contact-ObjektContact object
EmailAddressEmailAddress SMTP-E-Mail-AdressenSMTP email addresses. JavaScript-Objekt des Typs StringJavaScript String object
MeetingSuggestionMeetingSuggestion Ein Verweis auf ein Ereignis oder eine Besprechung. Beispielsweise würde Exchange 2013 den folgenden Text als Besprechungsvorschlag erkennen: Treffen wir uns morgen zum Mittagessen.A reference to an event or meeting. For example, Exchange 2013 would recognize the following text as a meeting suggestion: Let's meet tomorrow for lunch. MeetingSuggestion-ObjektMeetingSuggestion object
PhoneNumberPhoneNumber US-Telefonnummern, wie beispielsweise: (235) 555-0110United States telephone numbers; for example: (235) 555-0110 PhoneNumber-ObjektPhoneNumber object
TaskSuggestionTaskSuggestion Sätze in einer E-Mail, die zu Aktionen auffordern. Beispiel: Bitte aktualisieren Sie das Arbeitsblatt.Actionable sentences in an email. For example: Please update the spreadsheet. TaskSuggestion-ObjektTaskSuggestion object
URLUrl Eine Webadresse, die dem Speicherort im Netzwerk und Bezeichner für eine Webressource explizit angibt. Exchange Server erfordert keine Zugriffsprotokoll in der Webadresse und erkennt keine URLs, die im Linktext als Instanzen der Entität Url eingebettet sind. Exchange Server kann die folgenden Beispielen angleichen: www.youtube.com/user/officevideos https://www.youtube.com/user/officevideosA web address that explicitly specifies the network location and identifier for a web resource. Exchange Server does not require the access protocol in the web address, and does not recognize URLs that are embedded in link text as instances of the Url entity. Exchange Server can match the following examples: www.youtube.com/user/officevideos https://www.youtube.com/user/officevideos JavaScript-Objekt des Typs StringJavaScript String object


In der folgenden Abbildung wird gezeigt, auf welche Weise bekannte Entitäten für Add-Ins von Exchange Server und Outlook unterstützt werden und welche Aktionen Add-Ins mit bekannten Entitäten ausführen können. Weitere Informationen zur Verwendung dieser Entitäten finden Sie unter Abrufen von Entitäten in Ihrem Add-In und Aktivieren eines Add-Ins basierend auf dem Vorhandensein einer Entität.The following figure describes how Exchange Server and Outlook support well-known entities for add-ins, and what add-ins can do with well-known entities. See Retrieving entities in your add-in and Activating an add-in based on the existence of an entity for more details on how to use these entities.

Unterstützung bekannter Entitäten durch Exchange Server, Outlook und Add-InsHow Exchange Server, Outlook, and add-ins support well-known entities

Unterstützung und Verwendung bekannter Entitäten in der Mail-App

Berechtigungen zum Extrahieren von EntitätenPermissions to extract entities

Fordern Sie unbedingt im Add-In-Manifest die entsprechenden Berechtigungen an, um Entitäten in Ihrem JavaScript-Code extrahieren zu können oder damit Ihr Add-In basierend auf dem Vorhandensein bestimmter bekannter Entitäten aktiviert wird.To extract entities in your JavaScript code or to have your add-in activated based on the existence of certain well-known entities, make sure you have requested the appropriate permissions in the add-in manifest.

Die Angabe der standardmäßigen beschränkten Berechtigung erlaubt es Ihrem Add-in, die Entitäten Adress, MeetingSuggestionoder TaskSuggestion zu extrahieren. Wenn Sie eine der anderen Entitäten extrahieren möchten, müssen Sie die Berechtigungen „Element lesen“, „Element lesen/schreiben“ oder „Postfach lesen/schreiben“ angeben. Verwenden Sie zu diesem Zweck im Manifest das Element Permissions und geben Sie die entsprechende Berechtigung an —Restricted, ReadItem, ReadWriteItemoder ReadWriteMailbox—, wie im folgenden Beispiel dargestellt:Specifying the default restricted permission allows your add-in to extract the Address, MeetingSuggestion, or TaskSuggestion entity. To extract any of the other entities, specify read item, read/write item, or read/write mailbox permission. To do that in the manifest, use the Permissions element and specify the appropriate permission—Restricted, ReadItem, ReadWriteItem, or ReadWriteMailbox—as in the following example:

<Permissions>ReadItem</Permissions>

Abrufen von Entitäten in Ihrem Add-InRetrieving entities in your add-in

Solange der Betreff oder Text des Elements, das vom Benutzer angezeigt wird, Zeichenfolgen enthält, die Exchange und Outlook als bekannte Entitäten erkennen können, stehen diese Instanzen für Add-Ins zur Verfügung. Sie sind auch dann verfügbar, wenn das Add-In nicht basierend auf bekannten Entitäten aktiviert wird. Mit der entsprechenden Berechtigung können Sie mithilfe der Methoden getEntities und getEntitiesByType bekannte Entitäten abrufen, die in der aktuellen Nachricht oder dem aktuellen Termin vorhanden sind.As long as the subject or body of the item that is being viewed by the user contains strings that Exchange and Outlook can recognize as well-known entities, these instances are available to add-ins. They are available even if an add-in is not activated based on well-known entities. With the appropriate permission, you can use the getEntities or getEntitiesByType method to retrieve well-known entities that are present in the current message or appointment.

Die getEntities-Methode gibt ein Array von Entities-Objekten zurück, das alle bekannten Entitäten im Element enthält.The getEntities method returns an array of Entities objects that contains all the well-known entities in the item.

Wenn Sie an einem bestimmten Typ von Entitäten interessiert sind, verwenden Sie die GetEntitiesByType-Methode die ein Array mit einzig den gewünschten Entitäten zurückgibt. Die Enumeration "EntityType" stellt alle Arten von bekannten Entitäten dar, die Sie extrahieren können.If you're interested in a particular type of entities, use the getEntitiesByType method which returns an array of only the entities you want. The EntityType enumeration represents all the types of well-known entities you can extract.

Nach dem Aufruf von getEntities können Sie die zugehörige Eigenschaft des Objekts Entities verwenden, um ein Array von Instanzen eines Entitätstyps abzurufen. Abhängig vom Typ der Entität können die Instanzen im Array Zeichenfolgen sein oder bestimmten Objekten zugeordnet sein.After calling getEntities, you can then use the corresponding property of the Entities object to obtain an array of instances of a type of entity. Depending on the type of entity, the instances in the array can be just strings, or can map to specific objects.

Zum Abrufen von Adressen im Element, greifen Sie wie im Beispiel in der vorherigen Abbildung gezeigt auf das von getEntities().addresses[] zurückgegebene Array zu. Die Entities.addresses-Eigenschaft gibt ein Array von Zeichenfolgen zurück, die Outlook als Postanschriften erkennt. In ähnlicher Weise gibt die Eigenschaft "Entities.Contacts" ein Array von Contact-Objekten zurück, die Outlook als Kontaktinformationen erkennt . Tabelle 1 enthält den Objekttyp einer Instanz der jeweiligen unterstützten Entität.As an example seen in the earlier figure, to get addresses in the item, access the array returned by getEntities().addresses[]. The Entities.addresses property returns an array of strings that Outlook recognizes as postal addresses. Similarly, the Entities.contacts property returns an array of Contact objects that Outlook recognizes as contact information. Tables 1 lists the object type of an instance of each supported entity.

Im folgenden Beispiel wird gezeigt, wie Sie in einer Nachricht gefundene Adressen abrufen.The following example shows how to retrieve any addresses found in a message.

// Get the address entities from the item.
var 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.
}

Aktivieren eines Add-Ins basierend auf dem Vorhandensein einer EntitätActivating an add-in based on the existence of an entity

Eine andere Möglichkeit für die Verwendung von bekannten Entitäten besteht darin, dass Outlook Ihr Add-In basierend auf dem Vorhandensein eines oder mehrerer Typen von Entitäten im Betreff oder im Text des aktuell angezeigten Elements aktiviert. Geben Sie dazu eine Regel des Typs ItemHasKnownEntity im Add-In-Manifest an. Der einfache Typ EntityType stellt die verschiedenen Typen bekannter Entitäten dar, die von Regeln des Typs ItemHasKnownEntity unterstützt werden. Nachdem das Add-In aktiviert wurde, können Sie die Instanzen dieser Entitäten auch für eigene Zwecke abrufen, wie im vorherigen Abschnitt Abrufen von Entitäten in Ihrem Add-In beschrieben.Another way to use well-known entities is to have Outlook activate your add-in based on the existence of one or more types of entities in the subject or body of the currently viewed item. You can do so by specifying an ItemHasKnownEntity rule in the add-in manifest. The EntityType simple type represents the different types of well-known entities supported by ItemHasKnownEntity rules. After your add-in is activated, you can also retrieve the instances of such entities for your purposes, as described in the previous section Retrieving entities in your add-in.

Optional können Sie einen regulären Ausdruck in einer Regel des Typs ItemHasKnownEntity verwenden, um Instanzen einer Entität weiter einzugrenzen, sodass Outlook ein Add-In nur bei Vorhandensein bestimmter Instanzen der Entität aktiviert. Sie können beispielsweise einen Filter definierten, der die Nachricht nach Anschriftsentitäten mit Washingtoner Postleitzahlen durchsucht, die mit „98“ beginnen. Verwenden Sie zum Anwenden eines Filters auf die Entitätsinstanzen die Attribute RegExFilter und FilterName im Element Rule des Typs ItemHasKnownEntity.You can optionally apply a regular expression in an ItemHasKnownEntity rule, so as to further filter instances of an entity and have Outlook activate an add-in only on a subset of the instances of the entity. For example, you can specify a filter for the street address entity in a message that contains a Washington state zip code beginning with "98". To apply a filter on the entity instances, use the RegExFilter and FilterName attributes in the Rule element of the ItemHasKnownEntity type.

Ähnlich wie bei anderen Aktivierungsregeln können Sie mehrere Regeln angeben, um eine Regelsammlung für Ihr Add-In zu bilden. Im folgenden Beispiel wird eine Operation vom Typ „AND“ auf zwei Regeln angewendet: eine Regel des Typs ItemIs und eine Regel des Typs ItemHasKnownEntity. Diese Regelsammlung aktiviert das Add-In immer dann, wenn das aktuelle Element eine Nachricht ist und Outlook eine Adresse im Betreff oder im Text des Elements erkennt.Similar to other activation rules, you can specify multiple rules to form a rule collection for your add-in. The following example applies an "AND" operation on 2 rules: an ItemIs rule and an ItemHasKnownEntity rule. This rule collection activates the add-in whenever the current item is a message and Outlook recognizes an address in the subject or body of that item.

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


Im folgenden Beispiel wird mithilfe von getEntitiesByType des aktuellen Elements eine Variable addresses für die Ergebnisse der vorherigen Regelsammlung festgelegt.The following example uses getEntitiesByType of the current item to set a variable addresses to the results of the preceding rule collection.

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


Die folgende ItemHasKnownEntity-Regel aktiviert das Add-In, sobald eine URL im Betreff oder im Text des aktuellen Elements erkannt wird und diese URL die Zeichenfolge „youtube“ (ungeachtet von Groß-/Kleinschreibung) enthält.The following ItemHasKnownEntity rule example activates the add-in whenever there is a URL in the subject or body of the current item, and the URL contains the string "youtube", regardless of the case of the string.

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


Im folgenden Beispiel wird mithilfe von getFilteredEntitiesByName(name) des aktuellen Elements eine Variable videos festgelegt, um ein Array von Ergebnissen abzurufen, die mit dem regulären Ausdruck in der vorherigen Regel des Typs ItemHasKnownEntity übereinstimmen.The following example uses getFilteredEntitiesByName(name) of the current item to set a variable videos to get an array of results that match the regular expression in the preceding ItemHasKnownEntity rule.

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

Tipps zur Verwendung bekannter EntitätenTips for using well-known entities

Es gibt einige wenige Aspekte und Beschränkungen, die Sie beachten sollten, wenn Sie bekannte Entitäten in Ihrem Add-In verwenden. Die folgenden Angaben gelten, solange Ihr Mail-Add-in aktiviert ist, wenn der Benutzer ein Element liest, das Übereinstimmungen mit bekannten Entitäten enthält, unabhängig davon, ob Sie eine Regel des Typs ItemHasKnownEntity verwenden:There are a few facts and limits you should be aware of if you use well-known entities in your add-in. The following applies as long as your add-in is activated when the user is reading an item which contains matches of well-known entities, regardless of whether you use an ItemHasKnownEntity rule:

  • Sie können Zeichenfolgen, bei denen es sich um bekannte Entitäten handelt, nur dann extrahieren, wenn die Zeichenfolgen in Englisch vorliegen.You can extract strings that are well-known entities only if the strings are in English.

  • Sie können bekannte Entitäten nur aus den ersten 2.000 Zeichen in dem Textkörper des Elements extrahieren. Dieser Grenzwert hilft dabei, den Bedarf an Funktionalität und Leistung auszugleichen, sodass Exchange Server und Outlook nicht durch das Analysieren und Identifizieren von Instanzen bekannter Entitäten in großen Nachrichten und Terminen blockiert werden. Beachten Sie, dass dieser Grenzwert unabhängig davon gilt, ob das Add-In eine ItemHasKnownEntity-Regel angibt. Wenn das Add-In eine solche Regel verwendet, beachten Sie auch den Grenzwert für die Regelverarbeitung in Element 2 für Outlook-Eich Clients weiter unten.You can extract well-known entities from the first 2,000 characters in the item body, but not beyond that limit. This size limit helps balance the need for functionality and performance, so that Exchange Server and Outlook are not bogged down by parsing and identifying instances of well-known entities in large messages and appointments. Note that this limit is independent of whether the add-in specifies an ItemHasKnownEntity rule. If the add-in does use such a rule, note also the rule processing limit in item 2 below for the Outlook rich clients.

  • Sie können Entitäten aus Terminen extrahieren, bei denen es sich um Besprechungen handelt, die von einer anderen Person als dem Besitzer des Postfachs organisiert wurden. Sie können keine Entitäten aus Kalenderelementen extrahieren, bei denen es sich nicht um Besprechungen oder aber um vom Besitzer des Postfachs organisierte Besprechungen handelt.You can extract entities from appointments that are meetings organized by someone other than the mailbox owner. You cannot extract entities from calendar items that are not meetings, or meetings organized by the mailbox owner.

  • Sie können Entitäten vom Typ MeetingSuggestion nur aus Nachrichten extrahieren, nicht aus Terminen.You can extract entities of the MeetingSuggestion type from only messages but not appointments.

  • Sie können URLs extrahieren, die explizit im Elementtext angegeben sind, jedoch keine URLs, die in Linktext im Textkörper von HTML-Elementen eingebettet sind. Erwägen Sie stattdessen die Verwendung einer Regel des Typs ItemHasRegularExpressionMatch, um sowohl explizite als auch eingebettete URLs abzurufen. Legen Sie BodyAsHTML für PropertyName fest sowie einen regulären Ausdruck für RegExValue, der URLs abgleicht.You can extract URLs that exist explicitly in the item body, but not URLs that are embedded in hyperlinked text in HTML item body. Consider using an ItemHasRegularExpressionMatch rule instead to get both explicit and embedded URLs. Specify BodyAsHTML as the PropertyName, and a regular expression that matches URLs as the RegExValue.

  • Entitäten können nicht aus Elementen im Ordner "Gesendete Elemente" extrahiert werden.You cannot extract entities from items in the Sent Items folder.

Außerdem gilt Folgendes, wenn Sie eine ItemHasKnownEntity-Regel verwenden und es möglicherweise Auswirkungen auf die Szenarien hat, in denen Sie normalerweise erwarten, dass Ihr Add-In aktiviert wird:In addition, the following applies if you use an ItemHasKnownEntity rule, and may affect the scenarios where you'd otherwise expect your add-in to be activated:

  • Bei Verwendung von Regeln des Typs ItemHasKnownEntity gleicht Outlook Entitätszeichenfolgen unabhängig von dem im Manifest angegebenen Standardgebietsschema nur auf Englisch ab.When using the ItemHasKnownEntity rule, expect Outlook to match entity strings in only English regardless of the default locale specified in the manifest.

  • Wenn Ihr Add-In in einem Outlook-Rich-Client ausgeführt wird, wendet Outlook Regeln des Typs ItemHasKnownEntity auf das erste Megabyte des Elementtexts an, jedoch nicht auf darüber hinausgehenden Text.When your add-in is running on an Outlook rich client, expect Outlook to apply the ItemHasKnownEntity rule to the first megabyte of the item body and not to the rest of the body over that limit.

  • Sie können Regeln des Typs ItemHasKnownEntity nicht verwenden, um ein Add-In für Elemente im Ordner „Gesendete Elemente“ zu aktivieren.You cannot use an ItemHasKnownEntity rule to activate an add-in for items in the Sent Items folder.

Siehe auchSee also