Verwenden von Exchange-Webdiensten über ein Outlook-Add-In

Artikel
11/13/2024

Ihr Outlook-Add-In kann Exchange-Webdienste (EWS) aus einer Umgebung verwenden, die Exchange Server (lokal) ausführt. EWS ist ein Webdienst, der auf dem Server verfügbar ist und den Quellspeicherort für die Benutzeroberfläche des Add-Ins bereitstellt. Dieser Artikel enthält ein Beispiel, das zeigt, die ein Outlook-Add-In Informationen von EWS abrufen kann.

Wichtig

Legacy-Exchange-Token sind veraltet. Ab Februar 2025 werden wir ältere Exchange-Benutzeridentitäts- und Rückruftoken für Exchange Online Mandanten deaktivieren. Die Zeitleiste und Details finden Sie auf unserer Faq-Seite. Dies ist Teil der Secure Future Initiative von Microsoft, die Organisationen die Tools zur Verfügung stellt, die sie benötigen, um auf die aktuelle Bedrohungslandschaft zu reagieren. Exchange-Benutzeridentitätstoken funktionieren weiterhin für lokale Exchange-Instanzen. Die Authentifizierung geschachtelter Apps ist der empfohlene Ansatz für token in Zukunft.

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 bereitstellen, verhindern websiteübergreifende Skripterstellungsfehler die Ausführung Ihres Add-Ins. 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

Wichtig

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

Sie können die mailbox.makeEwsRequestAsync-Methode verwenden, um eine EWS-Anforderung an den lokalen Exchange-Server zu senden, der das Postfach des Benutzers hostet.

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, die daten enthält, die für den Vorgang relevant sind. EWS SOAP-Anforderungen und -Antworten folgen dem in der Datei Messages.xsd definierten Schema. Wie andere EWS-Schemadateien befindet sich die Datei Message.xsd im virtuellen IIS-Verzeichnis, das EWS hostet.

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 Data-Parameter .
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 alle relevanten Informationen abzurufen und diese Informationen entsprechend zu verarbeiten.

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 getElementsByTagName verwenden, 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, (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, (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 Betreffinformationen 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

FAI-Elemente (Folder Associated Information) 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 keine Authentifizierungsanmeldeinformationen für Ihre Anforderung 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.

Nur Add-In-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.

Freigeben über