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

Zur Initiierung eines EWS-Vorgangs mit der Methode makeEwsRequestAsync müssen Sie Folgendes angeben:To use the makeEwsRequestAsync method to initiate an 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 browserabhängigen Probleme zu beachten:When parsing a SOAP response from an EWS operation, note the following browser-dependent issues:

  • Geben Sie das Präfix für einen Tagnamen an, wenn Sie die DOM-Methode getElementsByTagName verwenden, damit 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, an 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")
             });
    

    In 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 die Inhalte eines Tags in einer EWS-Antwort abzurufen, wie unten dargestellt:Use the DOM property textContent to get the contents of a tag in an EWS response, as shown below:

       content = $.parseJSON(value.textContent);
    

    Weitere Eigenschaften wie innerHTML funktionieren für einige Tags in einer EWS-Antwort möglicherweise nicht in Internet Explorer.Other properties such as innerHTML may not work on Internet Explorer for some tags in an 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 getSubjectRequest auf, um die SOAP-Anforderung für das ausgewählte Element abzurufen. Anschließend werden die SOAP-Anforderung und die Rückrufmethode callback 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="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.
   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 zugreifen, die in EWS über die Methode makeEwsRequestAsync verfügbar sind. Falls Sie nicht mit EWS-Vorgängen vertraut sind und nicht wissen, wie Sie die Methode makeEwsRequestAsync verwenden können, um auf einen Vorgang zuzugreifen, können Sie mit einem Beispiel für eine SOAP-Anforderung beginnen, um Ihr Argument data anzupassen.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.

Im Folgenden wird beschrieben, wie Sie diemakeEwsRequestAsync-Methode verwenden können: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.
ExpandDL-VorgangExpandDL operation Zeigt die vollständige Mitgliedschaft von Verteilerlisten an.Displays the full membership of distribution lists.
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.
GetUserAvailability-VorgangGetUserAvailability operation Liefert detaillierte Informationen über die Verfügbarkeit einer Gruppe von Benutzern, Räumen und Ressourcen innerhalb eines bestimmten Zeitraums.Provides detailed information about the availability of a set of users, rooms, and resources within a specified time period.
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.
ResolveNames-VorgangResolveNames operation Löst nicht eindeutige E-Mail-Adressen und Anzeigenamen auf.Resolves ambiguous email addresses and display names.
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

FAI (zugeordnete Ordnerinformationen) Elemente können nicht aktualisiert (aus ein Add-in oder erstellt werden). Diese ausgeblendeten Nachrichten werden in einem Ordner gespeichert und werden verwendet, um eine Vielzahl von Einstellungen und zusätzliche Daten zu speichern. Einsetzen, um den Vorgang UpdateItem löst einen Fehler ErrorAccessDenied: "Office-Erweiterung ist nicht zulässig, so aktualisieren Sie diese Art von Element". Als Alternative können Sie die EWS Managed API verwenden, um diese Elemente aus einem Windows-Client oder eine Server-Anwendung zu aktualisieren. Vorsicht wird empfohlen, da interne, Diensttyp Datenstrukturen kann geändert werden und Ihre Lösung unterbrechen könnten.FAI (Folder Associated Information) items cannot be updated (or created) from an add-in. These hidden messages are stored in a folder and are used to store a variety of settings and auxiliary data. Attempting to use the UpdateItem operation will throw an ErrorAccessDenied error: "Office extension is not allowed to update this type of item". As an alternative, you may use the EWS Managed API to update these items from a Windows client or a server application. Caution is recommended as internal, service-type data structures are subject to change and could break your solution.

Authentifizierungs- und Berechtigungsabwägungen für „makeEwsRequestAsync“Authentication and permission considerations for makeEwsRequestAsync

Wenn Sie die MakeEwsRequestAsync -Methode verwenden, wird die Anforderung mithilfe der e-Mail-Kontoanmeldeinformationen des aktuellen Benutzers authentifiziert. Die MakeEwsRequestAsync -Methode verwaltet die Anmeldeinformationen für Sie, so, dass Sie keine Anmeldeinformationen zur Authentifizierung bei Ihrer Anforderung angeben.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.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.

Ihr Add-in muss die Berechtigung ReadWriteMailbox im Manifest-add-in mit der MakeEwsRequestAsync -Methode angeben. Informationen zum Verwenden der Berechtigung ReadWriteMailbox finden Sie im Abschnitt ReadWriteMailbox Berechtigung in Grundlegendes zu Outlook-add-in-Berechtigungen.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.

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

Siehe auchSee also

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: