API de complément Outlook

  • Article

Pour utiliser des API dans votre complément Outlook, vous devez spécifier l’emplacement de la bibliothèque Office.js, l’ensemble des conditions requises, le schéma et les autorisations. Vous allez principalement utiliser les API JavaScript Office exposées via l’objet Mailbox .

Bibliothèque Office.js

Pour interagir avec l’API de complément Outlook, vous devez utiliser les API JavaScript dans Office.js. Le réseau de distribution de contenu (CDN) de la bibliothèque est https://appsforoffice.microsoft.com/lib/1.1/hosted/Office.js. Les compléments soumis à AppSource doivent faire référence à Office.js par le biais de ce CDN et ne peuvent pas utiliser de référence locale.

Référencez le CDN dans une <script>balise<head> de la page web (fichier .html, .aspx ou .php) qui implémente l’interface utilisateur de votre complément.

<script src="https://appsforoffice.microsoft.com/lib/1.1/hosted/Office.js" type="text/javascript"></script>

L’ajout de nouvelles API ne modifie pas l’URL vers Office.js. La version de l’URL sera modifiée uniquement si un comportement d’API existant est interrompu.

Importante

Lorsque vous développez un complément pour une application cliente Office, référencez l’API JavaScript Office à partir de la <head> section de la page. Ainsi, l’API est entièrement initialisée avant les éléments Body.

Ensembles de conditions requises

Toutes les API Outlook appartiennent à l’ensemble de conditions requises pour la boîte aux lettres. L’ensemble de conditions requises Mailbox possède plusieurs versions, et chaque nouvel ensemble d’API publié appartient à une version supérieure de l’ensemble. Tous les clients Outlook ne prendront pas en charge l’ensemble d’API le plus récent lors de sa publication, mais si un client Outlook prend en charge un ensemble de conditions requises, toutes les API comprises dans cet ensemble seront également prises en charge.

Pour savoir dans quels clients Outlook le complément s’affiche, indiquez la version de l’ensemble de conditions requises dans le manifeste. Par exemple, si vous indiquez la version 1.3 de l’ensemble de conditions requises, le complément n’apparaîtra pas dans les clients Outlook qui ne prennent pas en charge la version minimale 1.3.

Le fait de spécifier un ensemble de conditions requises ne limite pas votre complément aux API de cette version. Si le complément spécifie l’ensemble de conditions requises version 1.1, mais est exécuté dans un client Outlook prenant en charge la version 1.3, le complément peut toujours utiliser les API v1.3. L’ensemble de conditions requises contrôle uniquement les clients Outlook dans lesquels le complément apparaît.

Pour vérifier la disponibilité des API à partir d’un ensemble de conditions requises de version supérieure à celle spécifiée dans le manifeste, vous pouvez utiliser l’API JavaScript standard :

if (item.somePropertyOrFunction) {
   item.somePropertyOrFunction...  
}

Remarque

Ces vérifications ne sont pas nécessaires pour les API appartenant à l’ensemble de conditions requises dont la version est la même que celle spécifiée dans le manifeste.

Spécifiez l’ensemble de conditions requises minimal prenant en charge l’ensemble d’API critique pour votre scénario, sans lequel les fonctionnalités de votre complément ne fonctionneront pas. Vous spécifiez l’ensemble de conditions requises dans le manifeste. Le balisage varie en fonction du manifeste que vous utilisez.

  • Manifeste de complément uniquement : utilisez l’élément <Requirements> . Notez que l’élément <enfant Methods> de <Requirements> n’est pas pris en charge dans les compléments Outlook. Vous ne pouvez donc pas déclarer la prise en charge de méthodes spécifiques.
  • Manifeste unifié pour Microsoft 365 : utilisez la propriété « extensions.capabilities ».

Pour plus d’informations, consultez Manifestes de complément Office et Présentation des ensembles de conditions requises de l’API Outlook.

Autorisations

Votre complément requiert les autorisations appropriées pour utiliser les API dont il a besoin. En général, vous devez spécifier l’autorisation minimum nécessaire pour votre complément.

Il existe quatre niveaux d’autorisations : restreint, élément en lecture, élément en lecture/écriture et boîte aux lettres en lecture/écriture. Pour plus d’informations. Pour plus de détails, voir Présentation des autorisations du complément Outlook.

Objet Mailbox

Les compléments Outlook utilisent principalement un sous-ensemble de l’API exposée via l’objet Mailbox. Pour accéder aux objets et aux membres spécifiques à utiliser dans les compléments Outlook, tels que l’objet Item , utilisez la propriété mailbox de l’objet Context pour accéder à l’objet Mailbox , comme illustré dans la ligne de code suivante.

// Access the Item object.
const item = Office.context.mailbox.item;

Importante

Lorsque vous appelez Office.context.mailbox.item un message, notez que le volet de lecture dans le client Outlook doit être activé. Pour obtenir des conseils sur la configuration du volet de lecture, consultez Utiliser et configurer le volet de lecture pour afficher un aperçu des messages.

En outre, les compléments Outlook peuvent utiliser les objets suivants.

  • Objet Office : pour l’initialisation.

  • Objet Context : pour l’accès au contenu et aux propriétés de langue d’affichage.

Pour plus d’informations sur l’utilisation de JavaScript dans les compléments Outlook, voir Compléments Outlook. Pour explorer l’API JavaScript Outlook, consultez la page de référence de l’API Outlook .

Voir aussi