Partager via

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

  • Article

Gérez les données personnalisées dans votre complément Outlook à l’aide des paramètres d’itinérance, des propriétés personnalisées ou des données de session. Ces options donnent accès à des données personnalisées qui sont uniquement accessibles 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.

Le tableau suivant fournit une vue d’ensemble des options disponibles pour gérer les données personnalisées dans les compléments Outlook.

Option de données personnalisées Ensemble de conditions requises minimales S’applique à Description
Paramètres d’itinérance 1.1 Boîte aux lettres Gère les données personnalisées dans la boîte aux lettres d’un utilisateur. Le complément qui définit les données personnalisées peut y accéder à partir d’autres appareils pris en charge où la boîte aux lettres de l’utilisateur est configurée. Les données stockées sont accessibles dans les sessions Outlook suivantes.
Propriétés personnalisées 1.1 Élément de courrier Gère les données personnalisées d’un élément de courrier dans la boîte aux lettres d’un utilisateur. Le complément qui définit les données personnalisées peut y accéder à partir de l’élément de courrier sur les appareils pris en charge où la boîte aux lettres de l’utilisateur est configurée. Les données stockées sont accessibles dans les sessions Outlook suivantes.
Données de session 1.11 Élément de courrier Gère les données personnalisées d’un élément de courrier dans la session Outlook actuelle de l’utilisateur. Le complément qui définit les données personnalisées ne peut y accéder qu’à partir de l’élément de courrier pendant sa composition.

Remarque

Pour plus d’informations sur les ensembles de conditions requises et leurs clients pris en charge, consultez Ensembles de conditions requises de l’API JavaScript Outlook.

Pour en savoir plus sur chaque option de données personnalisées, sélectionnez l’onglet applicable.

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.

Importante

Bien que l’API de complément Outlook limite l’accès à ces paramètres uniquement au complément qui les a créés, ces paramètres ne doivent pas être considérés comme du stockage sécurisé. Ils sont accessibles par d’autres services, tels que Microsoft Graph. Ils ne doivent pas être utilisés pour stocker des informations sensibles, telles que des informations d’identification utilisateur ou des jetons de sécurité.

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 Office.onReady . 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;

Office.onReady((info) => {
  if (info.host === Office.HostType.Outlook) {
    // 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

Pour reprendre 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. Ensuite, il conserve 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

Toujours dans l’exemple précédent, la fonction JavaScript suivante, removeAddInSetting, montre 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 Outlook session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

Essayez l’exemple de code dans Script Lab

Pour savoir comment créer et gérer un objet RoamingSettings, obtenez les Script Lab pour le complément Outlook et essayez l’exemple « Utiliser les paramètres de complément ». Pour en savoir plus sur Script Lab, consultez Explorer l’API JavaScript Office à l’aide de Script Lab.

Voir aussi