Obtenir et définir des métadonnées de complément pour un complément Outlook

  • Article

Vous pouvez gérer les données personnalisées dans votre complément Outlook en utilisant une des solutions suivantes :

  • Les paramètres d’itinérance, qui permettent de gérer des données personnalisées pour la boîte aux lettres d’un utilisateur.
  • Les propriétés personnalisées, qui permettent de gérer des données personnalisées pour un élément de boîte aux lettres d’un utilisateur.

Ces deux méthodes donnent accès à des données personnalisées accessibles uniquement par votre complément Outlook, mais chaque méthode stocke les données séparément de l’autre. Autrement dit, les données stockées via les paramètres d’itinérance ne sont pas accessibles par les propriétés personnalisées, et inversement. Les paramètres d’itinérance sont stockés dans la boîte aux lettres de l’utilisateur, tandis que les propriétés personnalisées sont stockées sur un message ou un rendez-vous. Les données stockées sont accessibles dans les sessions Outlook suivantes sur tous les facteurs de forme pris en charge par le complément.

Données personnalisées par boîte aux lettres : paramètres d’itinérance

You can specify data specific to a user's Exchange mailbox using the RoamingSettings object. Examples of such data include the user's personal data and preferences. Your mail add-in can access roaming settings when it roams on any device it's designed to run on (desktop, tablet, or smartphone).

Les modifications apportées à ces données sont stockées dans une copie en mémoire de ces paramètres pour la session Outlook en cours. Vous devez enregistrer explicitement tous les paramètres d’itinérance après les avoir mis à jour afin qu’ils soient disponibles la prochaine fois que l’utilisateur ouvre votre complément, sur le même appareil ou sur tout autre appareil pris en charge.

Format des paramètres d’itinérance

Les données dans un objet RoamingSettings sont stockées sous forme d’une chaîne sérialisée JavaScript Object Notation (JSON).

Voici un exemple de structure, en supposant qu’il existe trois paramètres d’itinérance définis nommés add-in_setting_name_0, add-in_setting_name_1et add-in_setting_name_2.

{
  "add-in_setting_name_0": "add-in_setting_value_0",
  "add-in_setting_name_1": "add-in_setting_value_1",
  "add-in_setting_name_2": "add-in_setting_value_2"
}

Chargement des paramètres d’itinérance

Un complément de messagerie charge généralement les paramètres d’itinérance dans le gestionnaire d’événements Office.initialize. L’exemple de code JavaScript suivant montre comment charger des paramètres itinérants existants et obtenir les valeurs de deux paramètres, customerName et customerBalance.

let _mailbox;
let _settings;
let _customerName;
let _customerBalance;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  // Initialize instance variables to access API objects.
  _mailbox = Office.context.mailbox;
  _settings = Office.context.roamingSettings;
  _customerName = _settings.get("customerName");
  _customerBalance = _settings.get("customerBalance");
}

Création ou affectation d’un paramètre d’itinérance

Dans l’exemple précédent, la fonction JavaScript suivante, setAddInSetting, montre comment utiliser la méthode RoamingSettings.set pour définir un paramètre nommé cookie avec la date du jour et conserver les données à l’aide de la méthode RoamingSettings.saveAsync pour enregistrer tous les paramètres d’itinérance dans la boîte aux lettres de l’utilisateur.

La set méthode crée le paramètre si le paramètre n’existe pas déjà et affecte le paramètre à la valeur spécifiée. La saveAsync méthode enregistre les paramètres d’itinérance de façon asynchrone. Cet exemple de code passe une fonction de rappel, saveMyAddInSettingsCallback, à saveAsync. Une fois l’appel asynchrone terminé, saveMyAddInSettingsCallback est appelé à l’aide d’un paramètre, asyncResult. Ce paramètre est un objet AsyncResult qui contient le résultat des détails relatifs à l’appel asynchrone. Vous pouvez utiliser le paramètre facultatif userContext pour transmettre des informations d’état de l’appel asynchrone à la fonction de rappel.

// Set a roaming setting.
function setAddInSetting() {
  _settings.set("cookie", Date());
  // Save roaming settings to the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

// Callback function after saving custom roaming settings.
function saveMyAddInSettingsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Suppression d’un paramètre d’itinérance

Pour étendre également les exemples précédents, la fonction JavaScript suivante, , removeAddInSettingmontre comment utiliser la méthode RoamingSettings.remove pour supprimer le cookie paramètre et enregistrer tous les paramètres d’itinérance dans la boîte aux lettres.

// Remove an add-in setting.
function removeAddInSetting()
{
  _settings.remove("cookie");
  // Save changes to the roaming settings for the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

Données personnalisées par élément dans une boîte aux lettres : propriétés personnalisées

Vous pouvez spécifier les données propres à un élément dans la boîte aux lettres de l’utilisateur à l’aide de l’objet CustomProperties. Par exemple, votre complément de messagerie peut catégoriser certains messages et noter la catégorie à l’aide d’une propriété personnalisée messageCategory. Si votre complément de messagerie crée des rendez-vous à partir de suggestions de réunion dans un message, vous pouvez utiliser une propriété personnalisée pour suivre chacun de ces rendez-vous. Cela garantit que si l’utilisateur ouvre à nouveau le message, votre complément de messagerie n’offre pas de créer le rendez-vous une deuxième fois.

Comme pour les paramètres d’itinérance, les modifications apportées aux propriétés personnalisées sont stockées dans des copies en mémoire des propriétés de la session Outlook en cours. Pour vous assurer que ces propriétés personnalisées seront disponibles dans la session suivante, utilisez CustomProperties.saveAsync.

Ces propriétés personnalisées spécifiques au complément et à l’élément ne sont accessibles qu’à l’aide de l’objet CustomProperties . Ces propriétés sont différentes des propriétés UserProperties personnalisées basées sur MAPI dans le modèle objet Outlook et des propriétés étendues dans les services Web Exchange (EWS). Vous ne pouvez pas accéder directement à CustomProperties l’aide du modèle objet Outlook, d’EWS ou de REST. Pour savoir comment accéder CustomProperties à l’aide d’EWS ou REST, consultez la section Obtenir des propriétés personnalisées à l’aide d’EWS ou REST.

Remarque

Les propriétés personnalisées sont disponibles uniquement pour le complément qui les a créées et uniquement par le biais de l’élément de courrier dans lequel elles ont été enregistrées. Pour cette raison, les propriétés définies en mode composition ne sont pas transmises aux destinataires de l’élément de courrier. Lorsqu’un message ou un rendez-vous avec des propriétés personnalisées est envoyé, ses propriétés sont accessibles à partir de l’élément dans le dossier Éléments envoyés . Pour permettre aux destinataires de recevoir les données personnalisées que votre complément définit, envisagez plutôt d’utiliser InternetHeaders .

Utilisation de propriétés personnalisées

Avant de pouvoir utiliser les propriétés personnalisées, vous devez les charger en appelant la méthode loadCustomPropertiesAsync. Une fois que vous avez créé le conteneur de propriétés, vous pouvez utiliser les méthodes set et get pour ajouter et récupérer des propriétés personnalisées. Vous devez utiliser la méthodesaveAsync pour enregistrer les modifications que vous apportez au conteneur de propriétés.

Remarque

Lorsque vous utilisez des propriétés personnalisées dans les compléments Outlook, gardez à l’esprit que :

  • Outlook sur Mac ne met pas en cache les propriétés personnalisées. Si le réseau de l’utilisateur tombe en panne, les compléments dans Outlook sur Mac ne peuvent pas accéder à leurs propriétés personnalisées.
  • Dans Outlook sur Windows, les propriétés personnalisées enregistrées en mode composition ne sont conservées qu’après la fermeture ou Office.context.mailbox.item.saveAsync l’appel de l’élément en cours de composition.

Exemple de propriétés personnalisées

L’exemple suivant montre un ensemble simplifié de fonctions et de méthodes pour un complément Outlook qui utilise des propriétés personnalisées. Vous pouvez utiliser cet exemple comme point de départ pour votre complément qui utilise des propriétés personnalisées.

Cet exemple inclut les fonctions et méthodes suivantes.

  • Office.initialize -- Initialise le complément et charge le conteneur de propriétés personnalisées depuis le serveur Exchange.

  • customPropsCallback : obtient le conteneur de propriétés personnalisé retourné par le serveur et l’enregistre localement pour une utilisation ultérieure.

  • updateProperty : définit ou met à jour une propriété spécifique, puis enregistre la modification dans le conteneur de propriétés local.

  • removeProperty : supprime une propriété spécifique du conteneur de propriétés, puis enregistre ces modifications.

let _mailbox;
let _customProps;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  _mailbox = Office.context.mailbox;
  _mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
}

// Callback function from loading custom properties.
function customPropsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
  else {
    // Successfully loaded custom properties,
    // can get them from the asyncResult argument.
    _customProps = asyncResult.value;
  }
}

// Get individual custom property.
function getProperty() {
  const myProp = _customProps.get("myProp");
}

// Set individual custom property.
function updateProperty(name, value) {
  _customProps.set(name, value);
  // Save all custom properties to the mail item.
  _customProps.saveAsync(saveCallback);
}

// Remove a custom property.
function removeProperty(name) {
  _customProps.remove(name);
  // Save all custom properties to the mail item.
  _customProps.saveAsync(saveCallback);
}

// Callback function from saving custom properties.
function saveCallback() {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Obtenir des propriétés personnalisées à l’aide de EWS ou REST

Pour obtenir CustomProperties à l’aide de EWS ou REST, vous devez commencer par déterminer le nom de sa base propriété étendue MAPI. Vous pouvez ensuite obtenir cette propriété de la même façon que vous pouviez obtenir toute propriété étendue de base MAPI.

Comment les propriétés personnalisées sont stockées sur un élément

Les propriétés personnalisées définies par un complément ne sont pas équivalentes aux propriétés basées sur MAPI normales. Les API de complément sérialisent tous les compléments CustomProperties en tant que charge utile JSON, puis les enregistrent dans une seule propriété étendue basée sur MAPI dont le nom est cecp-<app-guid> (<app-guid> est l’ID de votre complément) et le GUID du jeu de propriétés est {00020329-0000-0000-C000-000000000046}. (Pour plus d’informations sur cet objet, voirMS-OXCEXT 2.2.5 Propriétés d’Application de messagerie Personnalisées.) Vous pouvez ensuite utiliser EWS ou REST pour obtenir cette propriété basée MAPI.

Obtenir des propriétés personnalisées à l’aide de EWS

Votre complément de messagerie peut obtenir la CustomProperties propriété étendue basée sur MAPI à l’aide de l’opération GetItem EWS. Accédez GetItem côté serveur à l’aide d’un jeton de rappel ou côté client à l’aide de la méthode mailbox.makeEwsRequestAsync . Dans la GetItem demande, spécifiez la CustomProperties propriété basée sur MAPI dans son jeu de propriétés en utilisant les détails fournis dans la section précédente Comment les propriétés personnalisées sont stockées sur un élément.

L’exemple suivant montre comment obtenir un élément et ses propriétés personnalisées.

Importante

Dans l’exemple suivant, remplacez <app-guid> par l’ID de votre complément.

let request_str =
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
                   'xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"' +
                   'xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"' +
                   'xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">' +
        '<soap:Header xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"' +
                     'xmlns:wsa="http://www.w3.org/2005/08/addressing">' +
            '<t:RequestServerVersion Version="Exchange2010_SP1"/>' +
        '</soap:Header>' +
        '<soap:Body>' +
            '<m:GetItem>' +
                '<m:ItemShape>' +
                    '<t:BaseShape>AllProperties</t:BaseShape>' +
                    '<t:IncludeMimeContent>true</t:IncludeMimeContent>' +
                    '<t:AdditionalProperties>' +
                        '<t:ExtendedFieldURI ' +
                          'DistinguishedPropertySetId="PublicStrings" ' +
                          'PropertyName="cecp-<app-guid>"' +
                          'PropertyType="String" ' +
                        '/>' +
                    '</t:AdditionalProperties>' +
                '</m:ItemShape>' +
                '<m:ItemIds>' +
                    '<t:ItemId Id="' +
                      Office.context.mailbox.item.itemId +
                    '"/>' +
                '</m:ItemIds>' +
            '</m:GetItem>' +
        '</soap:Body>' +
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(
    request_str,
    function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
            console.log(asyncResult.value);
        }
        else {
            console.log(JSON.stringify(asyncResult));
        }
    }
);

Vous pouvez également obtenir plus de propriétés personnalisées si vous les spécifiez dans la chaîne de demande, comme les autres éléments ExtendedFieldURI.

Obtenir des propriétés personnalisées à l’aide de REST

Dans votre complément, vous pouvez construire votre requête REST contre les messages et événements pour obtenir ceux qui déjà ont des propriétés personnalisées. Dans la requête, spécifiez la propriété basée MAPICustomPropertiesdans son ensemble de propriété à l’aide des informations fournies dans la section précédenteComment les propriétés personnalisées sont stockées sur un élément.

L’exemple suivant montre comment obtenir tous les événements ayant des propriétés personnalisées définies par votre complément et vous assurer que la réponse inclut la valeur de la propriété pour vous permettre d’appliquer une logique de filtrage.

Importante

Dans l’exemple suivant, remplacez <app-guid> avec l’ID de votre complément.

GET https://outlook.office.com/api/v2.0/Me/Events?$filter=SingleValueExtendedProperties/Any
  (ep: ep/PropertyId eq 'String {00020329-0000-0000-C000-000000000046}
  Name cecp-<app-guid>' and ep/Value ne null)
  &$expand=SingleValueExtendedProperties($filter=PropertyId eq 'String
  {00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')

Pour plus exemples qui utilisent REST pour obtenir les propriétés étendues à valeur unique base MAPI, voir Obtenir singleValueExtendedProperty.

L’exemple suivant montre comment obtenir un élément et ses propriétés personnalisées. Dans la fonction de rappel pour la méthode done, item.SingleValueExtendedProperties contient la liste des propriétés personnalisées demandées.

Importante

Dans l’exemple suivant, remplacez <app-guid> par l’ID de votre complément.

Office.context.mailbox.getCallbackTokenAsync(
    {
        isRest: true
    },
    function (asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded
            && asyncResult.value !== "") {
            let item_rest_id = Office.context.mailbox.convertToRestId(
                Office.context.mailbox.item.itemId,
                Office.MailboxEnums.RestVersion.v2_0);
            let rest_url = Office.context.mailbox.restUrl +
                           "/v2.0/me/messages('" +
                           item_rest_id +
                           "')";
            rest_url += "?$expand=SingleValueExtendedProperties($filter=PropertyId eq 'String {00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')";

            let auth_token = asyncResult.value;
            $.ajax(
                {
                    url: rest_url,
                    dataType: 'json',
                    headers:
                        {
                            "Authorization":"Bearer " + auth_token
                        }
                }
                ).done(
                    function (item) {
                        console.log(JSON.stringify(item));
                    }
                ).fail(
                    function (error) {
                        console.log(JSON.stringify(error));
                    }
                );
        } else {
            console.log(JSON.stringify(asyncResult));
        }
    }
);

Comportement de la plateforme dans les messages

Le tableau suivant récapitule le comportement des propriétés personnalisées enregistrées dans les messages pour différents clients Outlook.

Scénario Outlook sur le web et sur le nouveau client Windows (préversion) Outlook classique sur Windows Outlook sur Mac
Nouvelle composition null null null
Répondre, répondre à tous null null null
Transférer null Charge les propriétés du parent null
Élément envoyé à partir d’une nouvelle composition null null null
Élément envoyé à partir de répondre ou répondre à tous null null null
Élément envoyé à partir de l’avance null Supprime les propriétés du parent si elles ne sont pas enregistrées null

Pour gérer la situation dans Outlook sur Windows :

  1. Vérifiez les propriétés existantes lors de l’initialisation de votre complément et conservez-les ou effacez-les si nécessaire.
  2. Lorsque vous définissez des propriétés personnalisées, incluez une propriété supplémentaire pour indiquer si les propriétés personnalisées ont été ajoutées en mode lecture. Cela vous aidera à différencier si la propriété a été créée en mode composition ou héritée du parent.
  3. Pour case activée si l’utilisateur transfère ou répond à un message, vous pouvez utiliser item.getComposeTypeAsync (disponible dans l’ensemble de conditions requises 1.10).

Voir aussi