Coincidencia de cadenas en un elemento de Outlook como entidades conocidasMatch strings in an Outlook item as well-known entities

Antes de enviar un mensaje o un elemento de convocatoria de reunión, Exchange Server analiza el contenido del elemento, identifica y marca determinadas cadenas en el asunto y en el cuerpo que son similares a entidades conocidas de Exchange (por ejemplo, direcciones de correo electrónico, números de teléfono y direcciones URL). Los mensajes y las convocatorias de reunión son entregadas por Exchange Server en una bandeja de entrada de Outlook con entidades conocidas marcadas.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.

Si usa la API de JavaScript para Office, puede obtener estas cadenas que coinciden con entidades específicas conocidas para su procesamiento posterior. También puede especificar una entidad conocida en una regla en el manifiesto del complemento para que Outlook pueda activar el complemento cuando el usuario visualice un elemento que contenga coincidencias con la entidad. Después, puede extraer y realizar una acción en las coincidencias de la entidad.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.

Es conveniente poder identificar o extraer estos casos partir de una cita o de un mensaje seleccionados.Being able to identify or extract such instances from a selected message or appointment is convenient. Por ejemplo, puede crear un servicio de búsqueda inversa de números de teléfono como un complemento de Outlook.For example, you can build a reverse phone look-up service as an Outlook add-in. El complemento puede extraer cadenas en el asunto o cuerpo del elemento que parecen un número de teléfono, realizar una búsqueda inversa y mostrar el propietario registrado de cada número de teléfono.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.

En este tema se presentan estas entidades conocidas, se muestran ejemplos de reglas de activación basadas en entidades conocidas y se explica cómo extraer coincidencias de entidad independientemente de que se hayan utilizado entidades en las reglas de activación.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.

Compatibilidad con entidades conocidasSupport for well-known entities

Exchange Server marca las entidades conocidas de un mensaje o un elemento de convocatoria de reunión después de que el remitente envíe el elemento y antes de que Exchange entregue el elemento al destinatario. Por lo tanto, solo se marcan los elementos que hayan pasado por el servicio de transporte en Exchange, y Outlook puede activar los complementos según estas marcas cuando el usuario los visualiza. Por el contrario, cuando el usuario está redactando un elemento o visualizando un elemento que se encuentra en la carpeta Elementos enviados, como el elemento no ha pasado a través del servicio de transporte, Outlook no puede activar los complementos según las entidades conocidas.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.

De forma similar, tampoco se pueden extraer entidades conocidas de elementos que estén siendo redactados o que se encuentren en la carpeta Elementos enviados, ya que estos elementos no han pasado a través del servicio de transporte y no han sido marcados. Para más información sobre los tipos de elementos compatibles con la activación, vea Reglas de activación para complementos de Outlook.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.

En la tabla siguiente se muestran las entidades que admiten y reconocen Exchange Server y Outlook (de ahí que se denominen "entidades conocidas") y el tipo de objeto de una instancia de cada entidad. El reconocimiento del lenguaje natural de una cadena como una de estas entidades se basa en un modelo de aprendizaje formado sobre una gran cantidad de datos. Por ello, el reconocimiento no es determinista. Vea Sugerencias para usar entidades conocidas si desea más información sobre las condiciones del reconocimiento.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.

Tabla 1: Entidades admitidas y sus tiposTable 1. Supported entities and their types

Tipo de entidadEntity type Condiciones para el reconocimientoConditions for recognition Tipo de objetoObject type
DirecciónAddress Direcciones postales de los Estados Unidos; por ejemplo: 1234 Main Street, Redmond, WA 07722. En general, para que se pueda reconocer una dirección, tiene que seguir la estructura de las direcciones postales estadounidenses e incluir la mayoría de los elementos siguientes: número de la calle, nombre de la calle, ciudad, estado y código postal. La dirección se puede especificar en una o varias líneas.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. Objeto JavaScript StringJavaScript String object
ContactContact Una referencia a la información de una persona como se reconoce en el lenguaje natural.A reference to a person’s information as recognized in natural language. El reconocimiento de un contacto depende del contexto.The recognition of a contact depends on the context. Por ejemplo, una firma al final de un mensaje, o el nombre de una persona que aparezca cerca de algunos de estos elementos: número de teléfono, dirección, dirección de correo electrónico o URL.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. Objeto ContactContact object
EmailAddressEmailAddress Direcciones de correo electrónico SMTP.SMTP email addresses. Objeto JavaScript StringJavaScript String object
MeetingSuggestionMeetingSuggestion Una referencia a un evento o encuentro. Por ejemplo, Exchange 2013 reconocería el siguiente texto como una sugerencia de encuentro: Quedamos mañana para comerA 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. Objeto MeetingSuggestionMeetingSuggestion object
PhoneNumberPhoneNumber Números de teléfono de Estados Unidos; por ejemplo: (235) 555-0110United States telephone numbers; for example: (235) 555-0110 Objeto PhoneNumberPhoneNumber object
TaskSuggestionTaskSuggestion Frases accionables de un mensaje de correo. Por ejemplo: Por favor, actualice la hoja de cálculo.Actionable sentences in an email. For example: Please update the spreadsheet. Objeto TaskSuggestionTaskSuggestion object
UrlUrl Una dirección Web que especifica explícitamente la ubicación de red y el identificador de un recurso web.A web address that explicitly specifies the network location and identifier for a web resource. Exchange Server no requiere el protocolo de acceso en la dirección Web y no reconoce las direcciones URL insertadas en el texto del enlace como ejemplos de la entidad Url.A 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/officevideoshttp://www.youtube.com/user/officevideos Exchange Server puede coincidir con los siguientes ejemplos: www.youtube.com/user/officevideos http://www.youtube.com/user/officevideosExchange Server can match the following examples: www.youtube.com/user/officevideos http://www.youtube.com/user/officevideos Objeto JavaScript StringJavaScript String object

La figura 1 describe cómo el Exchange Server y el soporte Outlook admiten entidades conocidas para complementos y qué pueden hacer éstos con las entidades conocidas. Consulte la información sobre la Recuperación de las entidades en su complemento y la Activación de un complemento sobre la base de la existencia de una entidad para obtener más detalles sobre cómo usar estas entidades.Figure 1 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.

Figura 1: Cómo Exchange Server, Outlook y los complementos admiten entidades conocidasFigure 1. How Exchange Server, Outlook and add-ins support well-known entities

Soporte y uso de entidades conocidas en aplicación de correo

Permisos para extraer entidadesPermissions to extract entities

Para extraer entidades en su código JavaScript o para que su complemento se active según la existencia de determinadas entidades conocidas, asegúrese de solicitar los permisos adecuados en el manifiesto del complemento.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.

Especificar el permiso restringido predeterminado permite la extracción de la entidad Address, MeetingSuggestion, o TaskSuggestion por parte del complemento.Specifying the default restricted permission allows your add-in to extract the Address, MeetingSuggestion, or TaskSuggestion entity. Para extraer cualquiera de las otras entidades, especifique el elemento de lectura, el elemento de lectura/escritura o el permiso de lectura/escritura de buzón de correo.To extract any of the other entities, specify read item, read/write item, or read/write mailbox permission. Para ello, en el manifiesto, use el elemento Permissions y especifique el permiso adecuado (Restricted, ReadItem, ReadWriteItem o ReadWriteMailbox), como en el ejemplo siguiente: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>

Recuperación de las entidades en el complementoRetrieving entities in your add-in

Siempre que el cuerpo o el asunto del elemento que se está viendo contenga cadenas que Exchange y Outlook pueden identificar como entidades conocidas, estas instancias se encontrarán disponibles para los complementos (aunque los complementos no estén activados en función de estas entidades). Con el permiso adecuado, puede usar el método getEntities o getEntitiesByType para recuperar entidades conocidas que se encuentran en el mensaje o la cita actual. El método getEntities devuelve una matriz de objetos Entities que contiene todas las entidades conocidas del elemento. Si está interesado en un tipo de entidades en particular, el método getEntitiesByType permite obtener una matriz que contiene únicamente las entidades que se especifican. La enumeración EntityType representa todos los tipos de entidades conocidas que se pueden extraer.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. The getEntities method returns an array of Entities objects that contains all the well-known entities in the item. 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.

Después de llamar a getEntities, puede usar la propiedad correspondiente del objeto Entities para obtener una matriz de instancias de un tipo de entidad. Dependiendo del tipo de entidad, las instancias de la matriz pueden ser simplemente cadenas o pueden estar asignadas a determinados objetos. Como el ejemplo en la figura 1, para obtener direcciones en el elemento, obtenga acceso a la matriz que devuelve getEntities().addresses[]. La propiedad Entities.addresses devuelve una matriz de cadenas que Outlook reconoce como direcciones postales. Del mismo modo, la propiedad Entities.contacts devuelve una matriz de objetos Contact que Outlook reconoce como información de contacto. La tabla 1 describe el tipo de objeto de una instancia de cada entidad admitida.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. As an example seen in Figure 1, 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.

El ejemplo siguiente muestra cómo recuperar direcciones que se encuentren en un mensaje.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.
}

Activar un complemento basándose en la existencia de una entidadActivating an add-in based on the existence of an entity

Otra forma de usar entidades conocidas es hacer que Outlook active el complemento basándose en la existencia de uno o más tipos de entidades en el asunto o el cuerpo del elemento visto actualmente. Para hacerlo, puede especificar una regla ItemHasKnownEntity en el manifiesto del complemento. El tipo simple EntityType representa los diferentes tipos de entidades conocidas admitidas por las reglas de ItemHasKnownEntity. Después de activar el complemento, también puede recuperar las instancias de esas entidades para sus propios fines, como se describe en la sección anterior Recuperar entidades del complemento.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.

De manera opcional, puede aplicar una expresión regular en una regla ItemHasKnownEntity para refinar el filtro de las instancias de una entidad y hacer que Outlook active un complemento solo en uno de los subconjuntos de las instancias de la entidad. Por ejemplo, puede especificar un filtro para la entidad de dirección postal en un mensaje que contenga un código postal del estado de Washington y que empiece por “98”. Para aplicar un filtro en las instancias de entidad, use los atributos RegExFilter y FilterName del elemento Rule del tipo 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.

Al igual que otras reglas de activación, puede especificar múltiples reglas para formar una colección de reglas para su complemento. En el siguiente ejemplo se aplica una operación "AND" en 2 reglas: una regla ItemIs y una regla ItemHasKnownEntity. Esta colección de reglas activa el complemento siempre que el elemento actual sea un mensaje y Outlook reconozca una dirección en el asunto o el cuerpo de ese elemento.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>

El ejemplo siguiente usa getEntitiesByType del elemento actual para establecer una variable addresses para los resultados de la colección de reglas anterior.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);

El ejemplo de regla ItemHasKnownEntity siguiente activa el complemento siempre que haya una dirección URL en el asunto o cuerpo del elemento actual y la dirección URL contenga la cadena "youtube", independientemente de si está en mayúsculas o minúsculas.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"/>

El ejemplo siguiente usa getFilteredEntitiesByName(name) del elemento actual para establecer una variable videos para obtener una matriz de resultados que coincidan con la expresión regular en la regla ItemHasKnownEntity precedente.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);

Sugerencias para usar entidades conocidasTips for using well-known entities

Existen algunos hechos y límites relacionados con el uso de entidades conocidas en un complemento que debe conocer. Las consideraciones siguientes se aplican siempre que un complemento se encuentra activado mientras el usuario lee un elemento que contiene coincidencias de entidades conocidas, independientemente de si usa o no una regla ItemHasKnownEntity: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:

  1. Puede extraer cadenas que sean entidades conocidas solo si las cadenas están en inglés.You can extract strings that are well-known entities only if the strings are in English.

  2. Puede extraer entidades conocidas de los primeros 2000 caracteres del cuerpo del elemento, pero no más allá de este límite. Este límite en el tamaño ayuda a equilibrar las funciones y el rendimiento, de manera que Exchange Server y Outlook no se estanquen durante el análisis y la identificación de instancias de entidades conocidas en mensajes y citas grandes. Tenga en cuenta que este límite es independiente del hecho de que el complemento especifique una regla ItemHasKnownEntity. Si el complemento usa esta regla, tenga en cuenta también el límite de procesamiento de reglas en el elemento 2 siguiente para los clientes Outlook enriquecidos.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.

  3. Se pueden extraer entidades de citas que sean reuniones organizadas por alguien que no sea el propietario del buzón de correo. No se pueden extraer entidades de elementos de calendario que no sean reuniones o que sean reuniones organizadas por el propietario del buzón.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.

  4. Se pueden extraer entidades del tipo MeetingSuggestion pero solamente de los mensajes, no de las citas.You can extract entities of the MeetingSuggestion type from only messages but not appointments.

  5. También se pueden extraer las URL que existan explícitamente en el cuerpo del elemento, pero no las URL incluidas en el texto de los hipervínculos en el cuerpo del elemento HTML. Considere usar una regla ItemHasRegularExpressionMatch en vez de las URL explícitas y las incluidas en hipervínculos. Especifique BodyAsHTML como PropertyName, y una expresión regular que coincida con las URL como RegExValue.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.

  6. No se pueden extraer entidades de elementos de la carpeta Elementos enviados.You cannot extract entities from items in the Sent Items folder.

Además, lo siguiente se aplica si se usa una regla ItemHasKnownEntity y podría afectar a los escenarios donde el complemento debería activarse: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:

  1. Cuando se usa la regla ItemHasKnownEntity, Outlook debería dar como resultado cadenas de entidades solo en inglés, independientemente de la configuración regional predeterminada que se especifique en el manifiesto.When using the ItemHasKnownEntity rule, expect Outlook to match entity strings in only English regardless of the default locale specified in the manifest.

  2. Cuando el complemento se ejecute en un cliente Outlook enriquecido, Outlook debe aplicar la regla ItemHasKnownEntity al primer megabyte del cuerpo de elemento y no al resto del cuerpo más allá de ese límite.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.

  3. No se puede usar una regla ItemHasKnownEntity para activar un complemento para elementos en la carpeta Elementos enviados.You cannot use an ItemHasKnownEntity rule to activate an add-in for items in the Sent Items folder.

Recursos adicionalesAdditional resources