Mettre en correspondance des chaînes dans un élément Outlook en tant qu’entités connues

  • Article

Avant d’envoyer un élément de message ou de demande de réunion, Exchange Server analyse le contenu de l’élément, identifie et marque certaines chaînes dans l’objet et le corps similaires aux entités connues d’Exchange (par exemple, adresses e-mail, numéros de téléphone, URL). Les demandes de réunion et les messages sont envoyés par Exchange Server dans une boîte de réception Outlook avec les entités connues marquées.

Importante

Les compléments Outlook contextuels basés sur des entités seront mis hors service au deuxième trimestre 2024. Le travail de mise hors service de cette fonctionnalité commencera en mai et se poursuivra jusqu’à la fin du mois de juin. Après juin, les compléments contextuels ne seront plus en mesure de détecter les entités dans les éléments de courrier pour effectuer des tâches sur ces derniers. Les API suivantes seront également mises hors service.

Pour réduire les interruptions potentielles, les éléments suivants seront toujours pris en charge une fois les compléments contextuels basés sur des entités mis hors service.

  • Une autre implémentation du bouton Participer à une réunion , qui est activé par les compléments de réunion en ligne, est en cours de développement. Une fois la prise en charge des compléments contextuels basés sur des entités terminée, les compléments de réunion en ligne passent automatiquement à l’implémentation alternative pour activer le bouton Participer à une réunion .
  • Les règles d’expression régulière continueront d’être prises en charge une fois les compléments contextuels basés sur des entités mis hors service. Nous vous recommandons de mettre à jour votre complément contextuel pour utiliser des règles d’expression régulière comme solution alternative. Pour obtenir des conseils sur la façon d’implémenter ces règles, voir Utiliser des règles d’activation d’expression régulière pour afficher un complément Outlook.

Pour plus d’informations, consultez Retrait des compléments Outlook contextuels basés sur des entités.

À l’aide de l’API JavaScript Office, vous pouvez obtenir ces chaînes qui correspondent à des entités connues spécifiques pour un traitement ultérieur. Vous pouvez également spécifier une entité connue dans une règle du manifeste du complément pour qu’Outlook puisse activer votre complément quand l’utilisateur affiche un élément contenant des correspondances pour cette entité. Vous pouvez extraire et effectuer une action sur des correspondances pour cette entité.

Remarque

Les fonctionnalités du complément Outlook qui dépendent de règles d’activation ne sont pas prises en charge lorsque le complément utilise un manifeste unifié pour Microsoft 365.

Pouvoir identifier ou extraire de telles instances à partir d’un message ou d’un rendez-vous sélectionné s’avère très pratique. Par exemple, vous pouvez créer un service de recherche sur annuaire inversé comme complément Outlook. Le complément peut extraire des chaînes dans l’objet ou le corps de l’élément semblable à un numéro de téléphone, effectuer une recherche sur annuaire inversé et afficher le propriétaire inscrit de chaque numéro de téléphone.

Cette rubrique présente ces entités connues, montre des exemples de règles d’activation en fonction de ces entités et explique comment extraire des correspondances d’entités indépendamment de l’utilisation d’entités dans les règles d’activation.

Prise en charge des entités connues

Exchange Server marque les entités connues dans un élément de message ou de demande de réunion après que l’élément a été envoyé par l’expéditeur et avant qu’il soit remis au destinataire. Ainsi, seuls les éléments ayant transité via Exchange sont marqués, et Outlook peut activer des compléments en fonction de ces marquages quand l’utilisateur affiche ces éléments. En revanche, quand l’utilisateur compose ou affiche un élément du dossier Éléments envoyés, Outlook ne peut pas activer les compléments en fonction des entités connues car l’élément n’a pas transité via Exchange.

De même, vous ne pouvez pas extraire les entités connues dans les éléments en cours de composition ou situés dans le dossier Éléments envoyés, car ces éléments n’ont pas transité via Exchange et ne sont pas marqués. Pour plus d’informations sur les types d’éléments qui prennent en charge l’activation, voir Règles d’activation pour les compléments Outlook.

Le tableau suivant répertorie les entités qu’Exchange Server et Outlook prennent en charge et reconnaissent (d’où le nom « entités connues »), et le type d’objet d’une instance de chaque entité. La reconnaissance du langage naturel d’une chaîne en tant que l’une de ces entités est fondée sur un modèle d’apprentissage qui a été testé sur une grande quantité de données. Par conséquent, la reconnaissance n’est pas déterministe. Pour plus d’informations sur les conditions de reconnaissance, voir Conseils d’utilisation des entités connues.

Type d’entité Conditions de reconnaissance Type d’objet
Adresse Adresses postales aux États-Unis. Par exemple, « 1234 Main Street, Redmond, WA 07722 ». En général, pour qu’une adresse soit reconnue, elle doit suivre la structure d’une adresse postale des États-Unis, où la plupart des éléments sont présents, à savoir numéro de rue, nom de rue, ville, État et code postal. L’adresse peut être spécifiée sur une ou plusieurs lignes. Objet JavaScript String
Contact Une référence aux informations d’une personne telles que reconnues en langage naturel. La reconnaissance d’un contact varie selon le contexte. Par exemple, une signature à la fin d’un message ou le nom d’une personne apparaissant à proximité des informations suivantes : un numéro de téléphone, une adresse, une adresse électronique et une URL. Objet Contact
EmailAddress Adresses électroniques SMTP. Objet JavaScript String
MeetingSuggestion Référence à un événement ou une réunion. Par exemple, Exchange reconnaît le texte suivant comme une suggestion de réunion : « Nous allons nous réunir demain pour le déjeuner ». Objet MeetingSuggestion
PhoneNumber Numéros de téléphone aux États-Unis. Par exemple, (235) 555-0110. Objet PhoneNumber
TaskSuggestion Phrases appelant une action. Par exemple, « Veuillez mettre à jour la feuille de calcul ». Objet TaskSuggestion
Url Adresse web qui spécifie explicitement l’identificateur et l’emplacement réseau d’une ressource web. Exchange Server ne nécessite pas le protocole d’accès dans l’adresse web et ne reconnaît pas les URL incorporées dans le texte du lien en tant qu’instances de l’entitéUrl. Exchange Server peut correspondre aux exemples suivants :www.youtube.com/user/officevideoshttps://www.youtube.com/user/officevideos Objet JavaScript String

La figure suivante décrit comment Exchange Server et Outlook prennent en charge les entités connues pour les compléments, et ce que les compléments peuvent faire avec des entités connues. Voir Récupération d’entités dans votre complément et Activation d’un complément basé sur l’existence d’une entité pour plus de détails sur l’utilisation de ces entités.

Prise en charge et utilisation d’entités connues dans un complément Outlook.

Autorisations d’extraction d’entités

Pour extraire les entités de votre code JavaScript ou pour activer votre complément à partir de l’existence de certaines entités connues, assurez-vous que vous avez demandé les autorisations appropriées dans le manifeste du complément.

La spécification de l’autorisation restreinte par défaut permet à votre complément d’extraire l’entité Address, MeetingSuggestionou TaskSuggestion . Pour extraire les autres entités, spécifiez l’autorisation d’élément de lecture, d’élément en lecture/écriture ou d’autorisation de boîte aux lettres en lecture/écriture dans le manifeste.

L’exemple suivant demande l’autorisation d’élément de lecture dans le manifeste.

<Permissions>ReadItem</Permissions>

Pour en savoir plus sur les autorisations de complément Outlook, voir Présentation des autorisations de complément Outlook.

Récupération d’entités dans votre complément

Tant que l’objet ou le corps de l’élément consulté par l’utilisateur contient des chaînes qu’Exchange et Outlook peuvent reconnaître comme des entités connues, ces instances sont disponibles pour les compléments, et ce même si un complément n’est pas activé en fonction des entités connues. Avec l’autorisation appropriée, vous pouvez utiliser la getEntities méthode ou getEntitiesByType pour récupérer les entités connues présentes dans le message ou le rendez-vous actuel.

La getEntities méthode retourne un tableau d’objets Entities qui contient toutes les entités connues dans l’élément.

Si vous êtes intéressé par un type particulier d’entités, utilisez la getEntitiesByTypeméthode qui retourne un tableau contenant uniquement les entités souhaitées. L’énumération EntityType représente tous les types d’entités connues que vous pouvez extraire.

Après avoir appelé getEntities, vous pouvez utiliser la propriété correspondante de l’objet Entities pour obtenir un tableau d’instances d’un type d’entité. Selon le type d’entité, les instances dans le tableau peuvent être seulement des chaînes, ou peuvent être mappés avec des objets spécifiques.

Comme dans l’exemple illustré dans la figure précédente, pour obtenir des adresses dans l’élément, accédez au tableau renvoyé par getEntities().addresses[]. La Entities.addresses propriété retourne un tableau de chaînes qu’Outlook reconnaît en tant qu’adresses postales. De même, la Entities.contacts propriété renvoie un tableau d’objets Contact qu’Outlook reconnaît en tant qu’informations de contact. Le tableau 1 répertorie le type d’objet d’une instance de chaque entité prise en charge.

L’exemple suivant illustre comment récupérer des adresses trouvées dans un message.

// 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.
}

Activation d’un complément basé sur l’existence d’une entité

Une autre façon d’utiliser des entités connues consiste à faire en sorte qu’Outlook active votre complément selon l’existence de types d’entités dans l’objet ou le corps de l’élément actuellement affiché. Pour ce faire, spécifiez une ItemHasKnownEntity règle dans le manifeste du complément. Le type simple EntityType représente les différents types d’entités connues prises en charge par ItemHasKnownEntity les règles. Une fois votre complément activé, vous pouvez également récupérer les instances de ces entités pour répondre à vos besoins, comme le décrit la section précédente Récupération d’entités dans votre complément.

Vous pouvez éventuellement appliquer une expression régulière dans une ItemHasKnownEntity règle afin de filtrer davantage les instances d’une entité et faire en sorte qu’Outlook active un complément uniquement sur un sous-ensemble des instances de l’entité. Par exemple, vous pouvez spécifier un filtre pour l’entité d’adresse dans un message qui contient un code postal de l’État de Washington commençant par « 98 ». Pour appliquer un filtre sur les instances d’entité, utilisez les RegExFilter attributs et FilterName dans l’élément Rule du type ItemHasKnownEntity .

Comme avec d’autres règles d’activation, vous pouvez spécifier plusieurs règles afin de former une collection de règles pour votre complément. L’exemple suivant applique une opération « AND » sur 2 règles : une ItemIs règle et une ItemHasKnownEntity règle. Cette collection de règles active le complément lorsque l’élément en cours est un message et qu’Outlook reconnaît une adresse dans l’objet ou le corps de cet élément.

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

L’exemple suivant utilise getEntitiesByType l’élément actuel pour définir une variable addresses sur les résultats de la collection de règles précédente.

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

L’exemple de règle suivant ItemHasKnownEntity active le complément chaque fois qu’il y a une URL dans l’objet ou le corps de l’élément actif, et que l’URL contient la chaîne « youtube », quelle que soit la casse de la chaîne.

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

L’exemple suivant utilise getFilteredEntitiesByName(name) l’élément actif pour définir une variable videos afin d’obtenir un tableau de résultats qui correspondent à l’expression régulière de la règle précédente ItemHasKnownEntity .

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

Conseils d’utilisation des entités connues

Si vous utilisez des entités connues dans votre complément, vous devez connaître certaines informations et limites. Les éléments suivants s’appliquent tant que votre complément est activé lorsque l’utilisateur lit un élément qui contient des correspondances d’entités connues, que vous utilisiez ou non une ItemHasKnownEntity règle.

  • Vous pouvez extraire des chaînes qui sont des entités connues uniquement si les chaînes sont en anglais.

  • Vous pouvez extraire des entités connues des 2 000 premiers caractères du corps de l’élément, mais pas au-delà. Cette limite de taille permet d’équilibrer le besoin de fonctionnalités et de performances, de sorte que Exchange Server et Outlook ne soient pas embourbés par l’analyse et l’identification des instances d’entités connues dans les messages et rendez-vous volumineux. Notez que cette limite est indépendante du fait que le complément spécifie ou non une ItemHasKnownEntity règle. Si le complément utilise une telle règle, notez également la limite de traitement des règles pour Outlook sur Windows et sur Mac plus loin dans cette section.

  • Vous pouvez extraire des entités à partir de rendez-vous, qui sont des réunions organisées par une personne autre que le propriétaire de la boîte aux lettres. Vous ne pouvez pas extraire d’entités à partir d’éléments de calendrier qui ne sont pas des réunions ou des réunions organisées par le propriétaire de la boîte aux lettres.

  • Vous pouvez extraire des entités du MeetingSuggestion type à partir de messages uniquement, mais pas de rendez-vous.

  • Vous pouvez extraire des URL qui existent de façon explicite dans le corps d’élément, mais pas des URL incorporées dans un texte de lien hypertexte du corps d’élément HTML. Envisagez plutôt d’utiliser une ItemHasRegularExpressionMatch règle pour obtenir des URL explicites et incorporées. Spécifiez BodyAsHTML comme PropertyName et une expression régulière qui correspond aux URL en tant que RegExValue.

  • Vous ne pouvez pas extraire d’entités à partir d’éléments du dossier Éléments envoyés .

En outre, les éléments suivants s’appliquent si vous utilisez une règle ItemHasKnownEntity et peuvent affecter les scénarios dans lesquels vous vous attendriez à ce que votre complément soit activé.

  • Lors de l’utilisation de la ItemHasKnownEntity règle, attendez-vous à ce qu’Outlook corresponde aux chaînes d’entité uniquement en anglais, quels que soient les paramètres régionaux par défaut spécifiés dans le manifeste.

  • Lorsque votre complément s’exécute dans Outlook sur Windows ou mac, attendez-vous à ce qu’Outlook applique la ItemHasKnownEntity règle au premier mégaoctet du corps de l’élément et non au reste du corps au-dessus de cette limite.

  • Vous ne pouvez pas utiliser une ItemHasKnownEntity règle pour activer un complément pour les éléments du dossier Éléments envoyés .

Voir aussi