Appeler des services Web à partir d’un complément Outlook

Article
05/20/2023

Votre complément peut utiliser les services Web Exchange (EWS) à partir d’un ordinateur exécutant Exchange Server, d’un service web disponible sur le serveur qui fournit l’emplacement source de l’interface utilisateur du complément ou d’un service web disponible sur Internet. Cette rubrique fournit des exemples expliquant comment un complément Outlook peut demander des informations à partir d’EWS.

Importante

Les appels et opérations EWS ne sont pas pris en charge dans les compléments exécutés dans Outlook sur iOS et Android.

La façon dont vous appelez un service web varie en fonction de l’emplacement du service web. Les tableaux suivants répertorient les différentes façons dont vous pouvez appeler un service web en fonction de l’emplacement.

Emplacement des services web	Méthode d’appel du service Web
Serveur Exchange qui héberge la boîte aux lettres cliente	Utilisez la méthode mailbox.makeEwsRequestAsync pour appeler les opérations EWS qui permettent d'ajouter des compléments de prise en charge. Le serveur Exchange qui héberge la boîte aux lettres expose également EWS.
Serveur web qui fournit l’emplacement source de l’interface utilisateur du complément	Appelez le service web au moyen des techniques JavaScript standard. Le code JavaScript présent dans le cadre de l’interface utilisateur s’exécute dans le contexte du serveur web qui fournit l’interface utilisateur. Il est donc capable d’appeler les services web sur ce serveur sans provoquer d’erreur de script intersite.
Tous les autres emplacements	Créez un proxy pour le service web sur le serveur web qui fournit l’emplacement source de l’interface utilisateur. Si vous n’indiquez pas de proxy, votre complément ne s’exécutera pas en raison d’erreurs de script intersites. L’un des moyens de fournir un proxy consiste à utiliser JSON/P. Pour plus d’informations, voir Confidentialité et sécurité pour les compléments Office.

Utilisation de la méthode makeEwsRequestAsync pour accéder aux opérations EWS

Vous pouvez utiliser la méthode mailbox.makeEwsRequestAsync pour effectuer une demande EWS auprès du serveur Exchange qui héberge la boîte aux lettres de l’utilisateur.

EWS prend en charge en charge différentes opérations sur un serveur Exchange, par exemple, les opérations au niveau de l’élément pour copier, rechercher, mettre à jour ou envoyer un élément, et les opérations au niveau du dossier pour créer, obtenir ou mettre à jour un dossier. Pour effectuer une opération EWS, créez une requête SOAP XML pour cette opération. Une fois l’opération terminée, vous obtenez une réponse SOAP XML qui contient les données correspondant à l’opération. Les demandes et les réponses SOAP EWS suivent le schéma défini dans le fichier Messages.xsd. Comme d’autres fichiers de schéma EWS, le fichier Message.xsd se trouve dans le répertoire virtuel IIS qui héberge EWS.

Pour utiliser la makeEwsRequestAsync méthode pour lancer une opération EWS, fournissez les éléments suivants :

XML de la requête SOAP pour cette opération EWS, en tant qu’argument du paramètre de données
Fonction de rappel (comme argument de rappel )
Toutes les données d’entrée facultatives pour cette fonction de rappel (en tant qu’argument userContext )

Une fois la requête SOAP EWS terminée, Outlook appelle la fonction de rappel avec un seul argument, qui est un objet AsyncResult . La fonction de rappel peut accéder à deux propriétés de l’objet AsyncResult : la value propriété, qui contient la réponse SOAP XML de l’opération EWS, et éventuellement, la asyncContext propriété, qui contient toutes les données passées en tant que userContext paramètre . En règle générale, la fonction de rappel analyse ensuite le code XML dans la réponse SOAP pour obtenir toutes les informations pertinentes et traite ces informations en conséquence.

Conseils pour l’analyse des réponses EWS

Lors de l’analyse d’une réponse SOAP à partir d’une opération EWS, notez les problèmes suivants dépendant du navigateur.

Spécifiez le préfixe d’un nom de balise lors de l’utilisation de la méthode getElementsByTagNameDOM afin d’inclure la prise en charge des Explorer Internet et de la vue web Trident.

getElementsByTagName se comporte différemment selon le type de navigateur. Par exemple, une réponse EWS peut contenir le code XML suivant (mis en forme et abrégé à des fins d’affichage).

<t:ExtendedProperty><t:ExtendedFieldURI PropertySetId="00000000-0000-0000-0000-000000000000" 
PropertyName="MyProperty" 
PropertyType="String"/>
<t:Value>{
...
}</t:Value></t:ExtendedProperty>

Le code, comme dans ce qui suit, fonctionne sur un navigateur comme Chrome pour obtenir le code XML entre les ExtendedProperty balises.

const mailbox = Office.context.mailbox;
mailbox.makeEwsRequestAsync(mailbox.item.itemId, function(result) {
     const response = $.parseXML(result.value);
     const extendedProps = response.getElementsByTagName("ExtendedProperty")
});

Pour la vue web Trident (Internet Explorer), vous devez inclure le t: préfixe du nom de la balise, comme suit.

const mailbox = Office.context.mailbox;
mailbox.makeEwsRequestAsync(mailbox.item.itemId, function(result) {
     const response = $.parseXML(result.value);
     const extendedProps = response.getElementsByTagName("t:ExtendedProperty")
});

Utilisez la propriété textContent DOM pour obtenir le contenu d’une balise dans une réponse EWS, comme suit.
```
content = $.parseJSON(value.textContent);
```
D’autres propriétés telles que innerHTML peuvent ne pas fonctionner sur la vue web Trident (Internet Explorer) pour certaines balises dans une réponse EWS.

Exemple

L’exemple suivant appelle makeEwsRequestAsync pour utiliser l’opération GetItem pour obtenir l’objet d’un élément. Cet exemple inclut les trois fonctions suivantes.

getSubjectRequest : prend un ID d’élément comme entrée et retourne le CODE XML de la requête SOAP à appeler GetItem pour l’élément spécifié.
sendRequest : appelle getSubjectRequest pour obtenir la requête SOAP pour l’élément sélectionné, puis passe la requête SOAP et la fonction de rappel, callback, à makeEwsRequestAsync pour obtenir l’objet de l’élément spécifié.
callback : traite la réponse SOAP qui inclut tout objet et d’autres informations sur l’élément spécifié.

function getSubjectRequest(id) {
   // Return a GetItem operation request for the subject of the specified item. 
   const result = 
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"' +
    '               xmlns:xsd="https://www.w3.org/2001/XMLSchema"' +
    '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
    '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
    '  <soap:Header>' +
    '    <RequestServerVersion Version="Exchange2013" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
    '  </soap:Header>' +
    '  <soap:Body>' +
    '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
    '      <ItemShape>' +
    '        <t:BaseShape>IdOnly</t:BaseShape>' +
    '        <t:AdditionalProperties>' +
    '            <t:FieldURI FieldURI="item:Subject"/>' +
    '        </t:AdditionalProperties>' +
    '      </ItemShape>' +
    '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
    '    </GetItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

   return result;
}

function sendRequest() {
   // Create a local variable that contains the mailbox.
   const mailbox = Office.context.mailbox;

   mailbox.makeEwsRequestAsync(getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
   const result = asyncResult.value;
   const context = asyncResult.context;

   // Process the returned response here.
}

Opérations EWS prises en charge par les compléments

Les compléments Outlook peuvent accéder à un sous-ensemble d’opérations disponibles dans EWS via la makeEwsRequestAsync méthode . Si vous n’êtes pas familiarisé avec les opérations EWS et comment utiliser la makeEwsRequestAsync méthode pour accéder à une opération, commencez par un exemple de requête SOAP pour personnaliser votre argument de données .

L’exemple suivant décrit comment utiliser la makeEwsRequestAsync méthode .

Dans le XML, remplacez les ID d’éléments et les attributs d’opération EWS par les valeurs appropriées.
Incluez la requête SOAP comme argument pour le paramètre de données de makeEwsRequestAsync.
Spécifiez une fonction de rappel et appelez makeEwsRequestAsync.
Dans la fonction de rappel, vérifiez les résultats de l’opération dans la réponse SOAP.
Utilisez les résultats de l’opération EWS en fonction de vos besoins.

Le tableau suivant répertorie les opérations EWS prises en charge par les compléments. Pour afficher des exemples de demandes et réponses SOAP, choisissez le lien correspondant à chaque opération. Pour plus d’informations sur les opérations EWS, voir Opérations EWS dans Exchange.

Opération EWS	Description
Opération CopyItem	Copie les éléments spécifiés et place les nouveaux éléments dans un dossier spécifique dans la banque d’informations Exchange.
Opération CreateFolder	Crée les dossiers dans l’emplacement spécifié dans la banque d’informations Exchange.
Opération CreateItem	Crée les éléments spécifiés dans la banque d’informations Exchange.
Opération ExpandDL	Affiche l’appartenance complète des listes de distribution.
Opération FindConversation	Énumère une liste des conversations dans le dossier spécifié dans la banque d’informations Exchange.
Opération FindFolder	Cherche les sous-dossiers d’un dossier donné et retourne un ensemble de propriétés qui décrit l’ensemble de sous-dossiers.
Opération FindItem	Identifie les éléments situés dans un dossier donné dans la banque d’informations Exchange.
Opération GetConversationItems	Obtient un ou plusieurs ensembles d’éléments organisés en nœuds dans une conversation.
Opération GetFolder	Obtient les propriétés spécifiées et le contenu des dossiers de la banque d’informations Exchange.
Opération GetItem	Obtient les propriétés spécifiées et le contenu des éléments de la banque d’informations Exchange.
Opération GetUserAvailability	Fournit des informations détaillées sur la disponibilité d’un ensemble d’utilisateurs, salles et ressources sur une période spécifiée.
Opération MarkAsJunk	Déplace les messages électroniques vers le dossier Courrier indésirable, et ajoute ou supprime les expéditeurs des messages de la liste des expéditeurs bloqués.
Opération MoveItem	Déplace les éléments dans un dossier de destination unique dans la banque d’informations Exchange.
Opération ResolveNames	Résout les adresses de messagerie et les noms d’affichage ambigus.
Opération SendItem	Envoie les messages électroniques situés dans la banque d’informations Exchange.
Opération UpdateFolder	Modifie les propriétés des dossiers existants dans la banque d’informations Exchange.
Opération UpdateItem	Modifie les propriétés des éléments existants dans la banque d’informations Exchange.

Remarque

Les éléments FAI (Informations relatives au dossier) ne peuvent pas être mis à jour (ni créés) depuis un complément. Ces messages masqués sont stockés dans un dossier et utilisés pour stocker divers paramètres et données auxiliaires. Si vous tentez d’utiliser l’opération UpdateItem, une erreur ErrorAccessDenied est générée : « L'annuaire d'entreprise n'est pas autorisé à mettre à jour ce type d'élément ». En guise d’alternative, vous pouvez utiliser l’API managée EWS pour mettre à jour ces éléments à partir d’un client Windows ou d’une application serveur. Soyez vigilant car les structures de données internes de type service peuvent être modifiées et sont susceptibles d’endommager votre solution.

Authentification et autorisation pour la méthode makeEwsRequestAsync

Lorsque vous utilisez la makeEwsRequestAsync méthode , la demande est authentifiée à l’aide des informations d’identification du compte de messagerie de l’utilisateur actuel. La makeEwsRequestAsync méthode gère les informations d’identification pour vous afin que vous n’ayez pas à fournir des informations d’identification d’authentification avec votre demande.

Remarque

L’administrateur de serveur doit utiliser l’applet de commande New-WebServicesVirtualDirectory ou Set-WebServicesVirtualDirectory pour définir le paramètre trueOAuthAuthentication sur sur le répertoire EWS du serveur d’accès au client afin de permettre à la makeEwsRequestAsync méthode d’effectuer des requêtes EWS.

Pour utiliser la makeEwsRequestAsync méthode , votre complément doit demander l’autorisation de lecture/écriture de boîte aux lettres dans le manifeste. Le balisage varie en fonction du type de manifeste.

Manifeste XML : définissez l’élément Permissions> sur<ReadWriteMailbox.
Manifeste unifié pour Microsoft 365 (préversion) : définissez la propriété « name » d’un objet dans le tableau « authorization.permissions.resourceSpecific » sur « Mailbox.ReadWrite.User ».

Pour plus d’informations sur l’utilisation de l’autorisation de boîte aux lettres en lecture/écriture , consultez Autorisation de boîte aux lettres en lecture/écriture.

Voir aussi

Consultez les rubriques suivantes pour la création de services principaux pour les compléments à l’aide de API Web ASP.NET.