Aufrufen von Webdiensten aus einem Outlook-Add-In

Ihr Mail-Add-in kann Exchange-Webdienste (EWS) auf einem Computer verwenden, auf dem Exchange Server 2013 ausgeführt wird, einen Webdienst, der auf dem Server, über den der Quellspeicherort für die Benutzeroberfläche des Add-Ins bereitgestellt wird, oder im Internet verfügbar ist. Dieser Artikel enthält ein Beispiel, das zeigt, die ein Outlook-Add-In Informationen von EWS abrufen kann.

Die zum Aufrufen eines Webdiensts gewählte Methode basiert auf dem Speicherort des Webdiensts. In der folgenden Tabelle sind die Methoden für unterschiedliche Speicherorte von Webdiensten angegeben.

Tabelle 1. Möglichkeiten zum Aufruf von Webdiensten aus einem Outlook-Add-In

Speicherort des Webdiensts Möglichkeit zum Aufruf des Webdienstes
Der Exchange Server dient als Host des Clientpostfachs. Verwenden Sie die mailbox.makeEwsRequestAsync-Methode, um EWS-Vorgänge aufzurufen, die Add-Ins unterstützen. Der Exchange Server hostet das Postfach hostet und stellt auch die Exchange-Webdienste zur Verfügung.
Der Webserver stellt den Quellspeicherort der Add-in-Benutzeroberfläche bereit. Rufen Sie den Webdienst mithilfe standardmäßiger JavaScript-Techniken auf. Der JavaScript im UI-Frame wird im Kontext des Webservers ausgeführt, der die Benutzeroberfläche (UI) bereitstellt. Deshalb können Webdienste auf diesem Server aufgerufen werden, ohne einen Fehler aufgrund von websiteübergreifendem Skripting zu verursachen.
Alle anderen Speicherorte. Erstellen Sie einen Proxy für den Webdienst auf dem Webserver, der den Quellspeicherort der Benutzeroberfläche bereitstellt. Wenn Sie keinen Proxy einrichten, kann Ihr Add-In aufgrund von Fehlern wegen websiteübergreifendem Skripting nicht ausgeführt werden. Eine Möglichkeit zum Bereitstellen eines solchen Proxys bietet JSON/P. Weitere Informationen finden Sie unter Datenschutz und Sicherheit bei Office-Add-Ins.

Die makeEwsRequestAsync-Methode zum Zugriff auf EWS-Vorgänge verwenden

Sie können die mailbox.makeEwsRequestAsync-Methode verwenden, um eine EWS-Anforderung an den Exchange-Server zu stellen, auf dem das Postfach des Benutzers gehostet wird.

Exchange-Webdienste unterstützen unterschiedliche Vorgänge auf einem Exchange Server, z. B. Vorgänge auf Elementebene zum Kopieren, Suchen, Aktualisieren oder Senden eines Elements und Vorgänge auf Ordnerebene zum Erstellen, Abrufen oder Aktualisieren eines Ordners. Erstellen Sie zum Durchführen eines EWS-Vorgangs eine XML-SOAP-Anforderung für den betreffenden Vorgang. Nach Abschluss des Vorgangs erhalten Sie eine XML-SOAP-Antwort mit den Daten, die für den Vorgang relevant sind. EWS-SOAP-Anforderungen und -Antworten basieren auf dem Schema, das in der Datei "Messages.xsd" definiert ist. Wie andere EWS-Schemadateien auch, ist die Datei "Message.xsd" in dem virtuellen IIS-Verzeichnis enthalten, von dem der Exchange Server gehostet wird.

Stellen Sie bitte Folgendes bereit, um die makeEwsRequestAsync-Methode zur Initiierung eines EWS-Vorgang zu verwenden:

  • Die XML für die SOAP-Anforderung für den EWS-Vorgang, als Argument für den data Parameter

  • Eine Rückrufmethode (als callback-Argument)

  • Sämtliche optionale Eingabedaten für die Rückrufmethode (als userContext-Argument)

Nach Abschluss der EWS-SOAP-Anforderung wird von Outlook die Rückrufmethode mit einem Argument aufgerufen, bei dem es sich um ein AsyncResult-Objekt handelt. Die Rückrufmethode kann auf zwei Eigenschaften des AsyncResult-Objekts zugreifen: auf die value-Eigenschaft , in der die XML-SOAP-Antwort des EWS-Vorgangs enthalten ist, und optional auf die asyncContext-Eigenschaft , in der alle als userContext-Parameter übergebenen Daten enthalten sind. Normalerweise analysiert die Rückrufmethode dann die XML-Daten in der SOAP-Anforderung, um relevante Informationen abzurufen, und verarbeitet diese Informationen entsprechend.

Tipps für die Analyse von EWS-Antworten

Bei der Analyse einer SOAP-Antwort von einem EWS-Vorgang sind die folgenden Browser-abhängigen Probleme zu beachten:

  • Geben Sie ein Präfix für einen Tagnamen an, wenn Sie die DOM-Methode getElementsByTagName verwenden, damit der Internet Explorer unterstützt wird.

    getElementsByTagName verhält sich je nach Browsertyp unterschiedlich. Eine EWS-Antwort kann z. B. den folgenden XML-Code (aus Anzeigegründen formatiert und abgekürzt) enthalten:

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

Mit dem folgenden Code können in einem Browser wie Chrome die XML-Daten, die von ExtendedProperty-Tags eingeschlossen sind, abgerufen werden:

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

Im Internet Explorer muss das t:-Präfix des Tagnamens auf folgende Weise eingeschlossen sein:

    var mailbox = Office.context.mailbox;
    mailbox.makeEwsRequestAsync(mailbox.item.itemId), function(result) {
        var response = $.parseXML(result.value);
        var extendedProps = response.getElementsByTagName("t:ExtendedProperty");
  • Verwenden Sie die DOM-Eigenschaft textContent, um Inhalte eines Tags in einer EWS-Antwort, wie im Folgenden dargestellt, abzurufen:
      content = $.parseJSON(value.textContent);

Weitere Eigenschaften wie innerHTML funktionieren möglicherweise nicht im Internet Explorer für einige Tags in einer EWS-Antwort.

Beispiel

Im folgenden Beispiel wird makeEwsRequestAsync aufgerufen, um den GetItem-Vorgang zum Abrufen des Betreffs eines Elements zu verwenden. Dieses Beispiel enthält die folgenden drei Funktionen:

  • getSubjectRequest: Verwendet eine Element-ID als Eingabe und gibt die XML-Daten für die SOAP-Anforderung zum Aufrufen von GetItem für das angegebene Element zurück.

  • sendRequest: Ruft getSubjectRequestauf, um die SOAP-Anforderung für das ausgewählte Element abzurufen. Anschließend werden die SOAP-Anforderung und die callback-Methode an makeEwsRequestAsync übergeben, um den Betreff des angegebenen Elements abzurufen.

  • callback: Verarbeitet die SOAP-Antwort, in der alle Informationen zum Betreff sowie die anderen Informationen zum angegebenen Element enthalten sind.

function getSubjectRequest(id) {
   // Return a GetItem operation request for the subject of the specified item. 
   var result = 
'<?xml version="1.0" encoding="utf-8"?>' +
'<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
'               xmlns:xsd="http://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.
   var mailbox = Office.context.mailbox;

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

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

   // Process the returned response here.
}

Von Add-Ins unterstützte EWS-Vorgänge

Outlook-Add-Ins können auf eine Teilmenge der Vorgänge, die in EWS über die makeEwsRequestAsync-Methode verfügbar sind, zugreifen. Falls Sie nicht mit EWS-Vorgängen vertraut sind und nicht wissen, wie Sie die makeEwsRequestAsync-Methode verwenden können, um auf einen Vorgang zuzugreifen, beginnen Sie mit einem SOAP-Anfordungsbeispiel, um Ihr data-Argument anzupassen. Im Folgenden wird beschrieben, wie Sie die makeEwsRequestAsync -Methode verwenden können:

  1. Ersetzen Sie in den XML-Daten alle Element-IDs und relevanten EWS-Vorgangsattribute durch die jeweils passenden Werte.

  2. Ordnen Sie die SOAP-Anforderung als Argument für den data-Parameter von makeEwsRequestAsync an.

  3. Geben Sie eine Rückrufmethode an, und rufen Sie makeEwsRequestAsync auf.

  4. Überprüfen Sie in der Rückrufmethode die Ergebnisse des Vorgangs in der SOAP-Antwort. Nutzen Sie diese Ergebnisse je nach Bedarf.

  5. Verwenden Sie die Ergebnisse des EWS-Vorgangs je nach Bedarf.

Die folgende Tabelle führt die EWS-Vorgänge auf, die von Add-Ins unterstützt werden. Klicken Sie für jeden Vorgang auf den entsprechenden Link, um Beispiele von SOAP-Anforderungen und -Antworten anzuzeigen. Weitere Informationen über EWS-Vorgänge finden Sie unter EWS-Operationen in Exchange.

Tabelle 2. Unterstützte EWS-Vorgänge

EWS-Vorgang Beschreibung
CopyItem-Vorgang Kopiert die angegebenen Elemente und fügt die neuen Elemente in einen bestimmten Ordner im Exchange-Speicher ein.
CreateFolder-Vorgang Erstellt Ordner am angegebenen Speicherort im Exchange-Speicher.
CreateItem-Vorgang Erstellt die angegebenen Elemente im Exchange-Speicher.
FindConversation-Vorgang Führt eine Liste mit Unterhaltungen im angegebenen Ordner im Exchange-Speicher auf.
FindFolder-Vorgang Sucht nach Unterordnern eines angegebenen Ordners und gibt Eigenschaften zurück, mit denen die Unterordner beschrieben werden.
FindItem-Vorgang Identifiziert Elemente, die in einem angegebenen Ordner im Exchange-Speicher enthalten sind.
GetConversationItems-Vorgang Ruft einen weiteren Elementesatz auf, der in einer Unterhaltung in Knoten angeordnet ist.
GetFolder-Vorgang Ruft die angegebenen Eigenschaften und den Inhalt von Ordnern aus dem Exchange-Speicher ab.
GetItem-Vorgang Ruft die angegebenen Eigenschaften und den Inhalt von Elementen aus dem Exchange-Speicher ab.
MarkAsJunk-Vorgang Verschiebt E-Mail-Nachrichten in den Ordner Junk-E-Mail und fügt Absender der Nachrichten entsprechend der Liste der blockierten Absender hinzu bzw. entfernt diese daraus.
MoveItem-Vorgang Verschiebt Elemente in einen gemeinsamen Zielordner im Exchange-Speicher.
SendItem-Vorgang Sendet E-Mail-Nachrichten, die sich im Exchange-Speicher befinden.
UpdateFolder-Vorgang Ändert die Eigenschaften bestehender Ordner im Exchange-Speicher.
UpdateItem-Vorgang Ändert die Eigenschaften bestehender Elemente im Exchange-Speicher.

Hinweis Zugeordnete Ordnerelemente (FAI) können nicht über ein Add-In aktualisiert (oder erstellt) werden. Diese ausgeblendeten Nachrichten werden in einem Ordner gespeichert und werden verwendet, um eine Vielzahl von Einstellungen und zusätzlichen Daten zu speichern. Beim Versuch, den UpdateItem-Vorgang zu verwenden, wird ein ErrorAccessDenied-Fehler ausgelöst: „Office-Erweiterungen sind für die Aktualisierung solcher Elemente nicht zulässig“. Alternativ können Sie die EWS Managed API verwenden, um diese Elemente über einen Windows-Client oder eine Serveranwendung zu aktualisieren. Hier ist allerdings Vorsicht geboten, da interne Diensttyp-Datenstrukturen Änderungen unterliegen und Ihre Lösung beschädigen können.

Authentifizierungs- und Berechtigungsabwägungen für die makeEwsRequestAsync-Methode

Bei Verwendung der makeEwsRequestAsync-Methode wird die Anforderung mithilfe der Anmeldeinformationen aus dem E-Mail-Konto des aktuellen Benutzers authentifiziert. Die makeEwsRequestAsync-Methode verwaltet die Anmeldeinformationen für Sie, damit Sie in Ihrer Anforderung keine Anmeldeinformationen zur Authentifizierung angeben müssen.

Hinweis Der Serveradministrator muss das Cmdlet New-WebServicesVirtualDirctory oder Set-WebServicesVirtualDirecory verwenden, um den OAuthAuthentication-Parameter im EWS-Verzeichnis des Clientzugriffsservers auf true festzulegen, damit die makeEwsRequestAsync-Methode zum Erstellen von EWS-Anforderungen aktiviert wird.

Für das Add-In muss die ReadWriteMailbox-Berechtigung im dazugehörigen Add-In-Manifest angegeben sein, damit die Methode makeEwsRequestAsync verwendet werden kann. Informationen zur Verwendung der ReadWriteMailbox-Berechtigung finden Sie im Abschnitt ReadWriteMailbox-Berechtigung unter Angeben von Berechtigungen für den Outlook-Add-In-Zugriff auf die Benutzerpostfächer.

Zusätzliche Ressourcen

Im folgenden Abschnitt finden Sie Informationen zum Erstellen von Back-End-Diensten für Add-Ins mit der ASP.NET Web-API: