Utiliser les services Web Exchange (EWS) à partir d’un complément Outlook.

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

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.

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

Vous pouvez utiliser la méthode mailbox.makeEwsRequestAsync pour envoyer une requête EWS au serveur Exchange local 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 des données pertinentes pour l’opération. Les requêtes et réponses SOAP EWS suivent le schéma défini dans le fichier Messages.xsd . Comme les 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 (en tant qu’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 getElementsByTagName DOM 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, (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, (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 .

1. Dans le XML, remplacez les ID d’éléments et les attributs d’opération EWS par les valeurs appropriées.

2. Incluez la requête SOAP comme argument pour le paramètre de données de makeEwsRequestAsync.

3. Spécifiez une fonction de rappel et appelez makeEwsRequestAsync.

4. Dans la fonction de rappel, vérifiez les résultats de l’opération dans la réponse SOAP.

5. 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.

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.

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 du complément uniquement : définissez l’élément Permissions> sur<ReadWriteMailbox.
• Manifeste unifié pour Microsoft 365 : 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

• Confidentialité et sécurité pour les compléments Office
• Résolutions des limites de stratégie d’origine identique dans les compléments Office
• Référence EWS pour Exchange
• Applications de messagerie pour Outlook et EWS dans Exchange

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

• Créer un service web pour un complément Office à l’aide de l’API Web ASP.NET
• Principes fondamentaux de la création d’un service HTTP à l’aide de l’API Web ASP.NET