Aufrufen von Webdiensten aus einem Outlook-Add-In

Artikel
04/12/2024

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

Wichtig

EWS-Aufrufe und -Vorgänge werden in Add-Ins, die in Outlook unter Android und iOS ausgeführt werden, nicht unterstützt.

Die Art und Weise, wie Sie einen Webdienst aufrufen, hängt davon ab, wo sich der Webdienst befindet. In den folgenden Tabellen sind die verschiedenen Methoden aufgeführt, wie Sie einen Webdienst basierend auf dem Standort aufrufen können.

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. Um einen EWS-Vorgang auszuführen, erstellen Sie eine XML-SOAP-Anforderung für diesen 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.

Um die makeEwsRequestAsync -Methode zum Initiieren eines EWS-Vorgangs zu verwenden, geben Sie Folgendes an:

Der XML-Code für die SOAP-Anforderung für diesen EWS-Vorgang als Argument für den Datenparameter
Eine Rückruffunktion (als Rückrufargument )
Alle optionalen Eingabedaten für diese Rückruffunktion (als userContext-Argument )

Wenn die EWS-SOAP-Anforderung abgeschlossen ist, ruft Outlook die Rückruffunktion mit einem Argument auf, bei dem es sich um ein AsyncResult-Objekt handelt. Die Rückruffunktion kann auf zwei Eigenschaften des AsyncResult Objekts zugreifen: die value -Eigenschaft, die die XML-SOAP-Antwort des EWS-Vorgangs enthält, und optional die -Eigenschaft, die asyncContext alle Daten enthält, die userContext als Parameter übergeben werden. In der Regel analysiert die Rückruffunktion dann den XML-Code in der SOAP-Antwort, um relevante Informationen abzurufen, und verarbeitet diese Informationen entsprechend.

Tipps für die Analyse von EWS-Antworten

Beachten Sie beim Analysieren einer SOAP-Antwort aus einem EWS-Vorgang die folgenden browserabhängigen Probleme.

Geben Sie das Präfix für einen Tagnamen an, wenn Sie die DOM-Methode getElementsByTagNameverwenden, um Unterstützung für Internet Explorer und die Trident-Webansicht einzuschließen.

getElementsByTagName verhält sich je nach Browsertyp unterschiedlich. Beispielsweise kann eine EWS-Antwort den folgenden XML-Code (formatiert und zu Anzeigezwecken abgekürzt) enthalten.

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

Code funktioniert wie im folgenden Beispiel in einem Browser wie Chrome, um den xml-Code abzurufen, der von den ExtendedProperty Tags eingeschlossen ist.

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

Für die Trident-Webansicht (Internet Explorer) müssen Sie das t: Präfix des Tagnamens wie folgt einschließen.

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

Verwenden Sie die DOM-Eigenschaft textContent , um den Inhalt eines Tags in einer EWS-Antwort wie folgt abzurufen.
```
content = $.parseJSON(value.textContent);
```
Andere Eigenschaften wie innerHTML funktionieren möglicherweise nicht in der Trident-Webansicht (Internet Explorer) für einige Tags in einer EWS-Antwort.

Beispiel

Im folgenden Beispiel wird aufgerufen makeEwsRequestAsync , um den Betreff eines Elements mithilfe des GetItem-Vorgangs abzurufen. Dieses Beispiel enthält die folgenden drei Funktionen.

getSubjectRequest – Akzeptiert eine Element-ID als Eingabe und gibt den XML-Code für den Aufruf GetItem der SOAP-Anforderung für das angegebene Element zurück.
sendRequest – Ruft auf getSubjectRequest , um die SOAP-Anforderung für das ausgewählte Element abzurufen, und übergibt dann die SOAP-Anforderung und die Rückruffunktion an , callbackum makeEwsRequestAsync den Betreff des angegebenen Elements abzurufen.
callback – Verarbeitet die SOAP-Antwort, die alle Themen und andere Informationen zum angegebenen Element enthält.

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

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

Outlook-Add-Ins können über die -Methode auf eine Teilmenge von Vorgängen zugreifen, die makeEwsRequestAsync in EWS verfügbar sind. Wenn Sie mit EWS-Vorgängen und der Verwendung der makeEwsRequestAsync -Methode für den Zugriff auf einen Vorgang nicht vertraut sind, beginnen Sie mit einem SOAP-Anforderungsbeispiel, um Ihr Datenargument anzupassen.

Im Folgenden wird beschrieben, wie Sie die makeEwsRequestAsync -Methode verwenden können.

Ersetzen Sie in den XML-Daten alle Element-IDs und relevanten EWS-Vorgangsattribute durch die jeweils passenden Werte.
Schließen Sie die SOAP-Anforderung als Argument für den Data-Parameter von ein makeEwsRequestAsync.
Geben Sie eine Rückruffunktion an, und rufen Sie auf makeEwsRequestAsync.
Überprüfen Sie in der Rückruffunktion die Ergebnisse des Vorgangs in der SOAP-Antwort.
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.

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.
ExpandDL-Vorgang	Zeigt die vollständige Mitgliedschaft von Verteilerlisten an.
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.
GetUserAvailability-Vorgang	Liefert detaillierte Informationen über die Verfügbarkeit einer Gruppe von Benutzern, Räumen und Ressourcen innerhalb eines bestimmten Zeitraums.
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.
ResolveNames-Vorgang	Löst nicht eindeutige E-Mail-Adressen und Anzeigenamen auf.
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 jederzeit geändert werden können, wodurch Ihre Lösung funktionsunfähig werden könnte.

Authentifizierungs- und Berechtigungsabwägungen für „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, sodass Sie für Ihre Anforderung keine Authentifizierungsanmeldeinformationen angeben müssen.

Hinweis

Der Serveradministrator muss das Cmdlet New-WebServicesVirtualDirectory oder Set-WebServicesVirtualDirectory verwenden, um den OAuthAuthAuthentication-Parameter im EWS-Verzeichnis des Clientzugriffsservers auf true festzulegen, damit die makeEwsRequestAsync Methode EWS-Anforderungen stellen kann.

Um die makeEwsRequestAsync -Methode verwenden zu können, muss Ihr Add-In die Lese-/Schreibberechtigung des Postfachs im Manifest anfordern. Das Markup variiert je nach Art des Manifests.

XML-Manifest: Legen Sie das <Permissions-Element> auf ReadWriteMailbox fest.
Einheitliches Manifest für Microsoft 365: Legen Sie die Eigenschaft "name" eines Objekts im Array "authorization.permissions.resourceSpecific" auf "Mailbox.ReadWrite.User" fest.

Informationen zur Verwendung der Lese-/Schreibberechtigung für Postfächer finden Sie unter Lese-/Schreibberechtigung für Postfächer.

Siehe auch

Informationen zum Erstellen von Back-End-Diensten für Add-Ins mit ASP.NET-Web-API finden Sie im Folgenden.