Aufrufen von Webdiensten aus einem Outlook-Add-InCall web services from an 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.Your add-in can use Exchange Web Services (EWS) from a computer that is running Exchange Server 2013, a web service that is available on the server that provides the source location for the add-in's UI, or a web service that is available on the Internet. This article provides an example that shows how an Outlook add-in can request information from EWS.

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.The way that you call a web service varies based on where the web service is located. Table 1 lists the different ways that you can call a web service based on location.

Tabelle 1. Möglichkeiten zum Aufruf von Webdiensten aus einem Outlook-Add-InTable 1. Ways to call web services from an Outlook add-in

Speicherort des WebdienstsWeb service location Möglichkeit zum Aufruf des WebdienstesWay to call the web service
Der Exchange Server dient als Host des Clientpostfachs.The Exchange server that hosts the client mailbox 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.Use the mailbox.makeEwsRequestAsync method to call EWS operations that add-ins support. The Exchange server that hosts the mailbox also exposes EWS.
Der Webserver stellt den Quellspeicherort der Add-in-Benutzeroberfläche bereit.The web server that provides the source location for the add-in UI 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.Call the web service by using standard JavaScript techniques. The JavaScript code in the UI frame runs in the context of the web server that provides the UI. Therefore, it can call web services on that server without causing a cross-site scripting error.
Alle anderen Speicherorte.All other locations 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.Create a proxy for the web service on the web server that provides the source location for the UI. If you do not provide a proxy, cross-site scripting errors will prevent your add-in from running. One way to provide a proxy is by using JSON/P. For more information, see Privacy and security for Office Add-ins.

Die makeEwsRequestAsync-Methode zum Zugriff auf EWS-Vorgänge verwendenUsing the makeEwsRequestAsync method to access EWS operations

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.You can use the mailbox.makeEwsRequestAsync method to make a EWS request to the Exchange server that hosts the user's mailbox.

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.EWS supports different operations on an Exchange server; for example, item-level operations to copy, find, update, or send an item, and folder-level operations to create, get, or update a folder. To perform a EWS operation, create an XML SOAP request for that operation. When the operation finishes, you get an XML SOAP response that contains data that is relevant to the operation. EWS SOAP requests and responses follow the schema defined in the Messages.xsd file. Like other EWS schema files, the Message.xsd file is located in the IIS virtual directory that hosts EWS.

Stellen Sie bitte Folgendes bereit, um die makeEwsRequestAsync-Methode zur Initiierung eines EWS-Vorgang zu verwenden:To use the makeEwsRequestAsync method to initiate a EWS operation, provide the following:

  • Die XML für die SOAP-Anforderung für den EWS-Vorgang, als Argument für den data ParameterThe XML for the SOAP request for that EWS operation, as an argument to the data parameter

  • Eine Rückrufmethode (als callback-Argument)A callback method (as the callback argument)

  • Sämtliche optionale Eingabedaten für die Rückrufmethode (als userContext-Argument)Any optional input data for that callback method (as the 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.When the EWS SOAP request is complete, Outlook calls the callback method with one argument, which is an AsyncResult object. The callback method can access two properties of the AsyncResult object: the value property, which contains the XML SOAP response of the EWS operation, and optionally, the asyncContext property, which contains any data passed as the userContext parameter. Typically, the callback method then parses the XML in the SOAP response to get any relevant information, and processes that information accordingly.

Tipps für die Analyse von EWS-AntwortenTips for parsing EWS responses

Bei der Analyse einer SOAP-Antwort von einem EWS-Vorgang sind die folgenden Browser-abhängigen Probleme zu beachten:When parsing a SOAP response from a EWS operation, note the following browser-dependent issues:

  • Geben Sie ein Präfix für einen Tagnamen an, wenn Sie die DOM-Methode getElementsByTagName verwenden, damit der Internet Explorer unterstützt wird.Specify the prefix for a tag name when using the DOM method getElementsByTagName, to include support for Internet Explorer.

    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:getElementsByTagName behaves differently depending on browser type. For example, a EWS response can contain the following XML (formatted and abbreviated for display purposes):

      <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:Code as in the following would work on a browser like Chrome to get the XML enclosed by the ExtendedProperty tags:

    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:On Internet Explorer, you must include the t: prefix of the tag name, as shown below:

    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:Use the DOM property textContent to get the contents of a tag in a EWS response, as shown below:
      content = $.parseJSON(value.textContent);

Weitere Eigenschaften wie innerHTML funktionieren möglicherweise nicht im Internet Explorer für einige Tags in einer EWS-Antwort.Other properties such as innerHTML may not work on Internet Explorer for some tags in a EWS response.

BeispielExample

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:The following example calls makeEwsRequestAsync to use the GetItem operation to get the subject of an item. This example includes the following three functions:

  • 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.getSubjectRequest -- Takes an item ID as input, and returns the XML for the SOAP request to call GetItem for the specified item.

  • 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.sendRequest -- Calls getSubjectRequest to get the SOAP request for the selected item, then passes the SOAP request and the callback method, callback, to makeEwsRequestAsync to get the subject of the specified item.

  • callback: Verarbeitet die SOAP-Antwort, in der alle Informationen zum Betreff sowie die anderen Informationen zum angegebenen Element enthalten sind.callback -- Processes the SOAP response which includes any subject and other information about the specified item.

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ängeEWS operations that add-ins support

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:Outlook add-ins can access a subset of operations that are available in EWS via the makeEwsRequestAsync method. If you are unfamiliar with EWS operations and how to use the makeEwsRequestAsync method to access an operation, start with a SOAP request example to customize your data argument. The following describes how you can use the makeEwsRequestAsync method:

  1. Ersetzen Sie in den XML-Daten alle Element-IDs und relevanten EWS-Vorgangsattribute durch die jeweils passenden Werte.In the XML, substitute any item IDs and relevant EWS operation attributes with appropriate values.

  2. Ordnen Sie die SOAP-Anforderung als Argument für den data-Parameter von makeEwsRequestAsync an.Include the SOAP request as an argument for the data parameter of makeEwsRequestAsync.

  3. Geben Sie eine Rückrufmethode an, und rufen Sie makeEwsRequestAsync auf.Specify a callback method and call makeEwsRequestAsync.

  4. Überprüfen Sie in der Rückrufmethode die Ergebnisse des Vorgangs in der SOAP-Antwort. Nutzen Sie diese Ergebnisse je nach Bedarf.In the callback method, verify the results of the operation in the SOAP response.

  5. Verwenden Sie die Ergebnisse des EWS-Vorgangs je nach Bedarf.Use the results of the EWS operation according to your needs.

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.The following table lists the EWS operations that add-ins support. To see examples of SOAP requests and responses, choose the link for each operation. For more information about EWS operations, see EWS operations in Exchange.

Tabelle 2. Unterstützte EWS-VorgängeTable 2. Supported EWS operations

EWS-VorgangEWS operation BeschreibungDescription
CopyItem-VorgangCopyItem operation Kopiert die angegebenen Elemente und fügt die neuen Elemente in einen bestimmten Ordner im Exchange-Speicher ein.Copies the specified items and puts the new items in a designated folder in the Exchange store.
CreateFolder-VorgangCreateFolder operation Erstellt Ordner am angegebenen Speicherort im Exchange-Speicher.Creates folders in the specified location in the Exchange store.
CreateItem-VorgangCreateItem operation Erstellt die angegebenen Elemente im Exchange-Speicher.Creates the specified items in the Exchange store.
FindConversation-VorgangFindConversation operation Führt eine Liste mit Unterhaltungen im angegebenen Ordner im Exchange-Speicher auf.Enumerates a list of conversations in the specified folder in the Exchange store.
FindFolder-VorgangFindFolder operation Sucht nach Unterordnern eines angegebenen Ordners und gibt Eigenschaften zurück, mit denen die Unterordner beschrieben werden.Finds subfolders of an identified folder and returns a set of properties that describe the set of subfolders.
FindItem-VorgangFindItem operation Identifiziert Elemente, die in einem angegebenen Ordner im Exchange-Speicher enthalten sind.Identifies items that are located in a specified folder in the Exchange store.
GetConversationItems-VorgangGetConversationItems operation Ruft einen weiteren Elementesatz auf, der in einer Unterhaltung in Knoten angeordnet ist.Gets one or more sets of items that are organized in nodes in a conversation.
GetFolder-VorgangGetFolder operation Ruft die angegebenen Eigenschaften und den Inhalt von Ordnern aus dem Exchange-Speicher ab.Gets the specified properties and contents of folders from the Exchange store.
GetItem-VorgangGetItem operation Ruft die angegebenen Eigenschaften und den Inhalt von Elementen aus dem Exchange-Speicher ab.Gets the specified properties and contents of items from the Exchange store.
MarkAsJunk-VorgangMarkAsJunk operation 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.Moves email messages to the Junk Email folder, and adds or removes senders of the messages from the blocked senders list accordingly.
MoveItem-VorgangMoveItem operation Verschiebt Elemente in einen gemeinsamen Zielordner im Exchange-Speicher.Moves items to a single destination folder in the Exchange store.
SendItem-VorgangSendItem operation Sendet E-Mail-Nachrichten, die sich im Exchange-Speicher befinden.Sends email messages that are located in the Exchange store.
UpdateFolder-VorgangUpdateFolder operation Ändert die Eigenschaften bestehender Ordner im Exchange-Speicher.Modifies the properties of existing folders in the Exchange store.
UpdateItem-VorgangUpdateItem operation Ändert die Eigenschaften bestehender Elemente im Exchange-Speicher.Modifies the properties of existing items in the Exchange store.

Hinweis Zugeordnete Ordnerelemente (FAI) können nicht über ein Add-In aktualisiert (oder erstellt) werden.Note FAI (Folder Associated Information) items cannot be updated (or created) from an add-in. Diese ausgeblendeten Nachrichten werden in einem Ordner gespeichert und werden verwendet, um eine Vielzahl von Einstellungen und zusätzlichen Daten zu speichern.These hidden messages are stored in a folder and are used to store a variety of settings and auxiliary data. 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“.Attempting to use the UpdateItem operation will throw an ErrorAccessDenied error: "Office extension is not allowed to update this type of item". Alternativ können Sie die EWS Managed API verwenden, um diese Elemente über einen Windows-Client oder eine Serveranwendung zu aktualisieren.As an alternative, you may use the EWS Managed API to update these items from a Windows client or a server application. Hier ist allerdings Vorsicht geboten, da interne Diensttyp-Datenstrukturen Änderungen unterliegen und Ihre Lösung beschädigen können.Caution is recommended as internal, service-type data structures are subject to change and could break your solution.

Authentifizierungs- und Berechtigungsabwägungen für die makeEwsRequestAsync-MethodeAuthentication and permission considerations for the makeEwsRequestAsync method

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.When you use the makeEwsRequestAsync method, the request is authenticated by using the email account credentials of the current user. The makeEwsRequestAsync method manages the credentials for you so that you do not have to provide authentication credentials with your request.

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.Note The server administrator must use the New-WebServicesVirtualDirectory or the Set-WebServicesVirtualDirectory cmldet to set the OAuthAuthentication parameter to true on the Client Access server EWS directory in order to enable the makeEwsRequestAsync method to make EWS requests.

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.Your add-in must specify the ReadWriteMailbox permission in its add-in manifest to use the makeEwsRequestAsync method. For information about using the ReadWriteMailbox permission, see the section ReadWriteMailbox permission in Understanding Outlook add-in permissions.

Zusätzliche RessourcenAdditional resources

Im folgenden Abschnitt finden Sie Informationen zum Erstellen von Back-End-Diensten für Add-Ins mit der ASP.NET Web-API:See the following for creating backend services for add-ins using ASP.NET Web API: