Freigeben über

Microsoft Office

Erkunden der JavaScript-API für Office: Mail-Apps

Angela Chu-Hatoun

Beispielcode herunterladen.

Dieser Artikel ist der vierte, der sich detailliert mit der JavaScript-API für Office beschäftigt. Der Schwerpunkt liegt diesmal auf dem API-Teil, der für Mail-Apps verfügbar ist, die von Outlook und Outlook Web App unterstützt werden. Dabei gehe ich davon aus, dass Sie einige allgemeine Kenntnisse über Apps für Office haben. Wenn Sie sich nicht sicher sind, erhalten Sie auf der Dev Center-Dokumentationsseite „Übersicht über Apps für Office“ (bit.ly/12nBWHG) alle für den Einstieg benötigten Informationen. Teil 1 dieser Reihe („Die neue JavaScript-API für Office“, verfügbar unter msdn.microsoft.com/magazine/jj891051) bietet einen breiten Überblick über das Objektmodell, welches das Office-Objekt als Stammobjekt aufweist. Das Mailbox-Objekt unterhalb von „Office.context“ bietet für die meisten der spezifischen Funktionen von Mail-Apps einen Einstiegspunkt im Objektmodell, und an dieser Stelle möchte ich inhaltlich einsetzen.

Das Ziel dieses Artikels ist, zu beschreiben, wie Sie als Entwickler die JavaScript-API für Office in Mail-Apps nutzen können. Unter msdn.microsoft.com/magazine/dn205107 finden Sie außerdem einen begleitenden Onlineartikel einschließlich des Quellcodes, in dem ich Schritt für Schritt eine Beispiel-Mail-App erläutere. Ich möchte jetzt auf verschiedene Features der JavaScript-API für Office eingehen und dazu mit grundlegenderen, häufig verwendeten Techniken beginnen, um schließlich zu erweiterten Konzepten überzugehen.

Grundlegende Features der JavaScript-API für Office

Das Mailbox-Objekt stellt den Zugriff auf das Benutzerprofil, das derzeit vom Benutzer ausgewählte Element, Formulare zum Anzeigen des Elements und eine Untermenge der Exchange-Webdienste zum Ändern von Elementen und Ordnern im Postfach bereit. Das Item-Objekt stellt das ausgewählte Nachrichten- oder Terminelement dar. Über dieses Objekt können Sie außerdem auf integrierte Eigenschaften, benutzerdefinierte Eigenschaften und Anhänge des Elements zugreifen.

Steuern der Aktivierung anhand des Elementtyps Um zu bestimmen, wann eine Mail-App aktiviert wird, können Sie Regeln im Manifest definieren. Das aktuell vom Benutzer ausgewählte und von „Mailbox.item“ angegebene Objekt kann ein Message-Objekt (einschließlich Besprechungsanfragen, Antworten und Absagen) oder ein Appointment-Objekt sein. Abhängig von Ihrem Szenario können Sie die Aktivierung der Mail-App auf nur einen bestimmten Elementtyp beschränken. Im folgenden XML-Beispiel wird eine ItemIs-Aktivierungsregel gezeigt. Durch diese wird die Mail-App nur bei Nachrichten aktiviert:

<Rule xsi:type="ItemIs" ItemType="Message" />

Mithilfe der JavaScript-API für Office können Sie die itemType-Eigenschaft verwenden, um den Typ des ausgewählten Elements zu überprüfen:

Office.context.mailbox.item.itemType

Elementzugriff und Eigenschaften Eine Basisfunktion von Mail-Apps ist der Zugriff auf das aktuell ausgewählte Element und dessen integrierte Eigenschaften.

Im folgenden JavaScript-Beispiel wird der Zugriff auf das ausgewählte Element und dessen integrierte Eigenschaft „subject“ gezeigt:

// The initialize function is required for all apps.
Office.initialize = function () {
  // Check for the DOM to load.
  $(document).ready(function () {
    var item = Office.context.mailbox.item;
    var subject = item.subject;
    // Continue processing the subject.
  });
}

Bekannte Entitäten Exchange Server erkennt bestimmte Entitäten, die unabhängig davon verfügbar sind, ob Sie Entitäten zum Aktivieren der Mail-App verwendet haben. Outlook und Outlook Web App extrahieren diese Entitäten, wenn sie im Betreff oder Text des ausgewählten Elements vorliegen, und machen sie durch die folgenden JavaScript-API-Methoden verfügbar:

  • getEntities-Methode
  • getEntitiesByType(entityType)-Methode
  • getFilteredEntitiesByName(name)-Methode

Zu den unterstützten Entitäten zählen unter anderem Adresse, Kontakt und E-Mail-Adresse.

Beachten Sie, dass Outlook und Outlook Web App nur Zeichenfolgen auf Englisch extrahieren. Die Standardsprache, die Sie im App-Manifest festlegen, spielt dabei keine Rolle. Outlook und Outlook Web App können im Ordner „Gesendete Objekte“ keine Entitäten extrahieren. Und sie können Besprechungsvorschläge in Nachrichten extrahieren, aber nicht in Terminen.

Abrufen von Übereinstimmungen, die zur kontextbezogenen Aktivierung führen Sie können Aktivierungsregeln festlegen, die auf Übereinstimmungen mit regulären Ausdrücken (ItemHasRegularExpressionMatch-Regeln) oder auf Übereinstimmungen mit Entitäten (ItemHasKnownEntity-Regeln) im ausgewählten Element abzielen. Mithilfe der folgenden Methoden erhalten Sie Übereinstimmungen mit regulären Ausdrücken. Die Methoden sind im übergeordneten Item-Objekt verfügbar, welches eine Nachricht oder ein Termin sein kann:

  • getRegExMatches-Methode
  • getRegExMatchesByName(name)-Methode

Um bestimmte Übereinstimmungen mit Entitäten abzurufen, verwenden Sie die Methoden, die oben im Abschnitt „Bekannte Entitäten“ aufgelistet sind. Unabhängig davon, welche Art von Aktivierungsregeln Sie für die Mail-App nutzen, können Sie diese Methoden jederzeit verwenden, um beliebige Übereinstimmungen mit Entitäten zu erhalten.

Beispiele Der folgende Code ist ein Bespiel für eine ItemHasRegularExpressionMatch-Regel namens „VideoURL“, durch welche die Mail-App aktiviert wird, wenn das ausgewählte Element eine Nachricht ist und der Nachrichtentext eine URL für ein Video auf YouTube enthält:

<Rule xsi:type="RuleCollection" Mode="And">
  <Rule xsi:type="ItemIs" ItemType="Message"/>
  <Rule xsi:type="ItemHasRegularExpressionMatch"
    RegExName="VideoURL"
    RegExValue="http://www\.youtube\.com/watch\?v=[a-zA-Z0-9_-]{11}"
    PropertyName="Body"/>
</Rule>

Das folgende JavaScript-Codebeispiel zeigt, wie die Item.getRegExMatches-Methode verwendet wird, um die Übereinstimmungen mit dem vorstehenden regulären VideoURL-Ausdruck zu erhalten:

Office.initialize = function () {
  // Check for the DOM to load.
  $(document).ready(function () {
    // Get an array of string matches for the regular expression VideoURL,
    // as specified in the manifest.
    var matches = Office.context.mailbox.item.getRegExMatches().VideoURL;
    // Continue processing the matches for the regular expression.
    });
}

Das nächste Beispiel demonstriert eine ItemHasKnownEntity-Regel, welche die Mail-App aktiviert, wenn im Betreff oder Text einer Nachricht eine Adresse enthalten ist:

<Rule xsi:type="RuleCollection" Mode="And">
  <Rule xsi:type="ItemIs" ItemType="Message"/>
  <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>

Das folgende JavaScript-Codebeispiel zeigt, wie die getEntitiesByType-Methode verwendet wird, um ein Array von Zeichenfolgen abzurufen, bei denen es sich um Postanschriften im Betreff oder Text der aktuell ausgewählten Nachricht handelt.

Office.initialize = function () {
  // Check for the DOM to load.
  $(document).ready(function () {
    var item = Office.context.mailbox.item;
    // Get an array of strings that represent postal
    // addresses in the current item.
    var addresses = item.getEntitiesByType(
      Office.MailboxEnums.EntityType.Address);
    // Continue processing the array of addresses.
  });
}

Die Aktivierung einer Mail-App anhand von Kontext – insbesondere Übereinstimmungen mit regulären Ausdrücken oder das Vorhandensein von bekannten Entitäten – ist leistungsstark und kann kompliziert zu debuggen sein. Tipps zum Debuggen von Schwierigkeiten bei der Aktivierung finden Sie im MSDN-Bibliotheksartikel „Problembehandlung für die Aktivierung von Mail-Apps“ unter bit.ly/11C0H30.

Datenspeicherung pro Element pro App Mit dem CustomProperties-Objekt können Sie elementspezifische Daten speichern, auf die nur Ihre Mail-App in einer Folgesitzung als benutzerdefinierte Eigenschaft des Elements zugreifen kann. Solche Daten werden als Schlüssel-Wert-Paar dargestellt. Wenn die App zur Ausführung auf mehreren Outlook-Clients und Formfaktoren entworfen wurde, wird Roaming für die benutzerdefinierten Eigenschaften mit dem unterstützten Outlook-Client und Formfaktor ausgeführt.

Die benutzerdefinierten Eigenschaften für ein Element sind durch die Item.loadCustomPropertiesAysnc-Methode verfügbar. Dies ist eine asynchrone Methode mit einer Abrufmethode als Parameter. Wenn die benutzerdefinierten Eigenschaften geladen sind, sind sie über die asyncResult.value-Eigenschaft verfügbar, welche als Eingabeparameter an die Abrufmethode übergeben wird. In Abbildung 1 wird gezeigt, wie benutzerdefinierte Eigenschaften für das aktuelle Element geladen, abgerufen, festgelegt und gespeichert werden.

Abbildung 1: Arbeiten mit benutzerdefinierten Eigenschaften für das aktuelle Element

Office.initialize = function () {
  var mailbox = Office.context.mailbox;
  mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
}
function customPropsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Succeeded) {
    var customProps = asyncResult.value;
    var myProp = customProps.get("myProp");
    customProps.set("otherProp", "value");
    customProps.saveAsync(saveCallback);
  }
  else {
    write (asyncResult.error.message);
  }
}
function saveCallback(asyncResult) {
  // Callback method to save custom properties.
}

Datenspeicherung pro Postfach pro App Mit dem RoamingSettings-Objekt können Sie benutzerdefinierte Daten speichern, auf die die Mail-App für dasselbe Postfach zugreifen kann, unabhängig davon, ob die Mail-App auf einem Desktop, Tablet oder Smartphone ausgeführt wird. Im folgenden JavaScript-Beispiel wird das Abrufen von postfachspezifischen Daten im initialize-Ereignishandler der Mail-App gezeigt:

var _mailbox;
var _settings;
Office.initialize = function () {
  // Check for the DOM to load using the jQuery ready function.
  $(document).ready(function () {
    // Initialize instance variables to access API objects.
    _mailbox = Office.context.mailbox;
    _settings = Office.context.roamingSettings;
    // Continue with app-specific code.
  });
}

Benutzerprofil Mit der Office.context.mailbox.userProfile-Eigenschaft können Sie auf das Profil des Benutzers zugreifen. Über das UserProfile-Objekt rufen Sie den Anzeigenamen, die SMTP-Adresse und die lokale Zeitzone des angemeldeten Benutzers ab. Das folgende JavaScript-Codebeispiel zeigt den Zugriff auf die UserProfile.emailAddress-Eigenschaft des aktuell in Outlook oder Outlook Web App angemeldeten Benutzers:

Office.initialize = function () {
  // Check for the DOM to load.
  $(document).ready(function () {
    var userProfile = Office.context.mailbox.userProfile;
    var SMTPAddress = userProfile.emailAddress;
    // Continue with processing the user's SMTP address. 
  });
}

Anzeigen von Outlook-Formularen In Outlook können Benutzer bestimmte Formulare für die Standardanzeige von Terminen und Nachrichten festlegen. Mit den folgenden Methoden in der JavaScript-API für Office kann eine Mail-App einen Termin bzw. eine Nachricht anzeigen und dabei dieselben Formulare wie Outlook verwenden:

  • Mailbox.displayAppointmentForm(itemId)
  • Mailbox.displayMessageForm(itemId)

Der Code in Abbildung 2 prüft, ob ein Benutzer einen Termin ausgewählt hat, und zeigt diesen mit dem Outlook-Standardterminformular an.

Abbildung 2: Prüfen, ob der Benutzer einen Termin ausgewählt hat

var myOm;
var myItem;
Office.initialize = function () {
  $(document).ready(function () {
    myOm = Office.context.mailbox;
    // Get the selected item.
    myItem = myOm.item;
    // Display the selected appointment.
    displaySelectedAppointment();
  });
}
function displaySelectedAppointment() {
  // Display selected item only if the item is an appointment.
  if (myitem.itemType == Office.MailboxEnums.ItemType.Appointment)
  {
    myOm.displayAppointmentForm(myItem.itemId);
  }
  else
  {
    // Handle condition as appropriate.
  }
}

Mit der Mailbox.displayNewAppointmentForm-Methode können Sie Werte bestimmten Feldern in einem Terminformular für eine neue Besprechung zuweisen und das Formular anzeigen, damit der Benutzer den Termin ausfüllt. Legen Sie diese Felder beim Aufrufen der Methode als eine Liste von Zeichenfolgen-Wert-Paaren fest, wie in Abbildung 3 gezeigt.

Abbildung 3: Zuweisen von Werten zu bestimmten Feldern im Formular für einen neuen Termin

var myOm;
Office.initialize = function () {
  $(document).ready(function () {
    myOm = Office.context.mailbox;
    // After the DOM is loaded, can display the
    // pre-populated new appointment form.
    displayFormForNewAppointment();
  });
}
function displayFormForNewAppointment(){
  var formParameters =
  {
    "requiredAttendees" : ["wendy@contoso.com", "derek@contoso.com"],
    "optionalAttendees" : ["shane@contoso.com", "michael@contoso.com"],
    "start" : new Date("September 27, 2012 11:15:00"),
    "end" : new Date("("September 27, 2012 12:30:00"),
    "location" : "Conf room 200",
    "resources" : ['sound', 'lighting', 'recording'],
    "subject" : "Next rehearsal",
    "body" : "This is about the next rehearsal."
  }
  // Display a form to create an appointment with
  // the specified fields in the form.
  myOm.displayNewAppointmentForm(formParameters);
}

Den meisten Raum zur Anpassung bieten die Methoden, die Antwortformulare für einen Termin oder eine Nachricht anzeigen:

  • Appointment.displayReplyAllForm(htmlBody)-Methode
  • Appointment.displayReplyForm(htmlBody)-Methode
  • Message.displayReplyAllForm(htmlBody)-Methode
  • Message.displayReplyForm(htmlBody)-Methode

Mit jeder dieser Methoden können Sie eine HTML-Zeichenfolge bereitstellen, die den Text des Antwortformulars darstellt. Das Beispiel in Abbildung 4 zeigt ein Formular für eine Antwort an alle auf eine Nachricht.

Abbildung 4: Angeben des HTML-Codes für ein Formular für eine Antwort an alle für ein Nachrichtenelement

var myOm;
var myItem;
Office.initialize = function () {
  // Check for the DOM to load.
  $(document).ready(function () {
    myOm = Office.context.mailbox;
    // Get the selected item.
    myItem = myOm.item;
    // After the DOM is loaded, display
    // the reply form.
    displayReply();
  });
}
function displayReply(){
  // Display a reply form to the sender and recipients only
  // if the selected item is a message.
  if (myitem.itemType == Office.MailboxEnums.ItemType.Message) {
      myItem.displayReplyAllForm
      ("<html><head><head><body>This is the body of " +
       "the email reply.</body></html>");
  }
}

Erweiterte Konzepte

Abrufen von Elementanlagen Eine Mail-App kann die JavaScript-API für Office und Rückruftoken der Exchange-Webdienste verwenden, um auf Anlagen der aktuell ausgewählten Nachricht oder des Termins im Benutzerpostfach zuzugreifen. Durch das Rückruftoken kann serverseitiger Back-End-Code der Mail-App – oder von Drittanbieter-Webdiensten – verwendet werden, um den GetAttachment-Vorgang der Exchange-Webdienste aufzurufen und tatsächlich die bestimmten Anlagen abzurufen.

Im folgenden Text wird beschrieben, wie eine Mail-App Anhänge abruft. Der Prozess wird auch in Abbildung 5 gezeigt:

  1. Eine Mail-App fordert mit „Mailbox.getCallbackTokenAsync“ ein Rückruftoken an. Sie ruft mit „Item.attachments“ Metadaten über die Anhänge des ausgewählten Termins oder der Nachricht ab (einschließlich Anhangs-IDs), und ruft mithilfe von „Mailbox.ewsUrl“ die URL des Endpunkts der Exchange-Webdienste für das aktuelle E-Mail-Konto ab.
  2. Die Mail-App übergibt das Rückruftoken, die Anhangs-IDs und die URL des Endpunkts der Exchange-Webdienste an den serverseitigen Code.
  3. Der serverseitige Code ruft den GetAttachment-Vorgang der Exchange-Webdienste auf, um die eigentlichen Anhänge aus dem Exchange-Speicher abzurufen.

Mail Apps Accessing Attachments from an Exchange Server
Abbildung 5: Mail-Apps greifen auf Anhänge auf einem Exchange-Server zu

Beachten Sie, dass der serverseitige Code durch direkt erstellte Anforderungen an die Exchange-Webdienste auf diese zugreifen muss. Die Mailbox.makeEws­RequestAsync-Methode kann nicht verwendet werden, um auf den GetAttachment-Vorgang zuzugreifen. Zum Zeitpunkt der Erstellung dieses Artikels wird der Zugriff auf Anhänge unterstützt, wenn die Mail-App in Outlook Web App ausgeführt wird. Das Feature ist nicht verfügbar, wenn die Mail-App in Outlook ausgeführt wird.

Im MSDN-Codebeispiel „Mail-Apps für Office: Abrufen von Anhängen von einem Exchange-Server” (bit.ly/11dG9fS) finden Sie ein Beispiel dafür, wie Sie auf Anhänge in einer Mail-App zugreifen.

Benutzertoken für einmaliges Anmelden Ihre Mail-App kann verbreitete Authentifizierungstechniken für das Web nutzen, um Benutzer zu authentifizieren und zu autorisieren. Wenn Sie die Authentifizierung für das einmalige Anmelden für die Benutzer übergreifend für Outlook und Outlook Web App unterstützen möchten, verwenden Sie die Exchange-Identitätstoken, indem Sie die Mailbox.getUserIdentityTokenAsync-Methode aufrufen.

Das einmalige Anmelden basiert auf einem Exchange-Server, der ein Exchange-Identitätstoken für das E-Mail-Konto auf diesem Exchange-Server zuweist. Ein Exchange-Identitätstoken enthält mehrere Felder, darunter eine Signatur zur Überprüfung des Tokens und einen eindeutigen Bezeichner, der das Exchange-E-Mail-Konto darstellt.

In der Regel kann eine Mail-App, die Benutzer authentifiziert, mit einem Webdienst interagieren – der serverseitiger Code für die Mail-App sein kann – oder einem Webdienst eines Drittanbieters, der seinen eigenen Identitätsprovider (IdP) verwendet, um die Benutzeridentität in einem verbundenen Identitätssystem zu überprüfen. Der Schlüssel für das einmalige Anmelden ist die Zuordnung, die der Webdienst zwischen der eindeutigen ID (aus dem Exchange-Identitätstoken) und der Benutzeridentität (die dem IdP bekannt ist) vornimmt.

Abbildung 6 bietet eine Übersicht über die Authentifizierung mithilfe von Exchange-Identitätstoken.

In der folgenden Liste ist der Vorgang zusammengefasst:

  1. Die Mail-App ruft „Mailbox.getUserIdentityTokenAsync“ auf, um ein Exchange-Identitätstoken für den Benutzer anzufordern, und legt eine Rückrufmethode fest, die ausgeführt wird, wenn die asynchrone Abrufoperation abgeschlossen wird.
  2. Die Rückruffunktion ruft das Exchange-Identitätstoken ab und übergibt es zur Authentifizierung an den Webdienst.
  3. Der Webdienst erhält vom Exchange-Server einen öffentlichen Schlüssel, um das Token zu überprüfen.
  4. Abhängig davon, ob der Benutzer sich vorher angemeldet hat, setzt der Webdienst den Prozess folgendermaßen fort:
    1. Wenn der Benutzer sich das erste Mal bei der Mail-App anmeldet, ist für dieses Konto keine frühere Zuordnung vorhanden, und der Webdienst antwortet der Mail-App, dass diese den Benutzer zum Eingeben der Anmeldeinformationen auffordern soll. Wenn die Mail-App die Anmeldeinformationen erhalten hat, übergibt sie diese an den Webdienst.
    2. Der Dienst erstellt anschließend eine Zuordnung zwischen der eindeutigen, vom Token bereitgestellten ID und der Benutzeridentität aus den Anmeldeinformationen, die dem IdP bekannt sind. Mithilfe der Anmeldeinformationen kann der Dienst den Benutzer anmelden.
    3. Bei Folgeanmeldungen: Wenn der Benutzer von einem Desktop, Tablet, Browser oder Smartphone aus die Mail-App in Outlook oder Outlook Web App öffnet, werden folgende Schritte ausgeführt:
      1. Die Mail-App ruft „getUserIdentityTokenAsync“ auf und erhält in dem Token dieselbe eindeutige ID.
      2. Die Mail-App übergibt das Token an den Webdienst.
      3. Der Webdienst überprüft das Token.
      4. Der Webdienst sucht anschließend die Zuordnungstabelle, sucht den Benutzer und autorisiert den Zugriff.

Authentication Using Exchange Identity Tokens
Abbildung 6: Authentifizierung mithilfe von Exchange-Identitätstoken

Nachdem Sie das Token überprüft haben, können Sie den Benutzer angemeldet lassen, sogar wenn er die Mail-App von einer anderen Hostanwendung oder einem anderen Gerät aus öffnet.

Die Details für die Authentifizierung und Überprüfung sind ziemlich komplex. Sie können die Managed API-Überprüfungsbibliothek in den Exchange-Webdiensten verwenden, um den Prozess zu vereinfachen. Mit dieser Überprüfungsbibliothek erstellt ein Webdienst ein Objekt. Er extrahiert das Token und fügt es diesem Objekt hinzu, Er überprüft, ob die Signatur gültig ist, und wenn sie es ist, fügt er der Zuordnungsdatenbank den eindeutigen Bezeichner hinzu.

Weitere Informationen zur Verwendung von Exchange-Identitätstoken zur Authentifizierung finden Sie in der folgenden Dev Center-Dokumentation:

  • „Authentifizieren einer Mail-App mithilfe von Exchange-Identitätstoken“ (bit.ly/ZYaZ9v)
  • „Innenleben des Exchange-Identitätstokens“ (bit.ly/ZxRogq)
  • „Vorgehensweise: Aufrufen eines Diensts mithilfe eines Identitätstokens in Exchange“ (bit.ly/12jqxcU)
  • „Vorgehensweise: Verwenden der Exchange-Tokenüberprüfungsbibliothek“ (bit.ly/11akmEg)
  • „Vorgehensweise: Überprüfen eines Exchange-Identitätstokens“ (bit.ly/15im6SO)
  • „Vorgehensweise: Authentifizieren eines Benutzers mit einem Identitätstoken für Exchange“ (bit.ly/13gZ36T)

Codebeispiele:

  • Im C#-Codebeispiel für Visual Studio 2012 „Mail-Apps für Outlook: Verwenden eines Clientidentitätstokens“ (bit.ly/ZxS85b) finden Sie ein C#-Beispiel für eine Mail-App und einen Webdienst, die zur Authentifizierung Exchange-Identitätstoken verwenden.
  • Unter „Mail-Apps für Outlook: Überprüfen eines Clientidentitätstokens mithilfe von .NET Framework“ (bit.ly/17j9FSZ) finden Sie ein Beispiel dafür, wie Sie .NET Framework verwenden, um ein Clientidentitätstoken zu überprüfen.

Zugriff auf eine Untergruppe der Exchange-Webdienste Mithilfe der Mailbox.makeEwsRequestAsync-Methode können Mail-Apps auf eine Untergruppe der Exchange-Webdienstvorgänge zugreifen, um ein Element oder einen Ordner zu erstellen, zu suchen, abzurufen, zu aktualisieren oder zu verschieben. Sie können beispielsweise mit dem CreateItem-Vorgang einen Termin, eine Nachricht oder einen Kontakt erstellen. Mit dem FindItem-Vorgang können Sie Elemente in einem Postfach suchen. Und Sie können den SendItem-Vorgang verwenden, um eine Nachricht oder eine Besprechungsanfrage zu senden. Die unterstützte Vorgangsuntergruppe betrifft nur das Postfach des Benutzers. Andere Vorgänge der Exchange-Webdienste, die eine gesamte Organisation betreffen – zum Beispiel der Zugriff auf die globale Adressliste oder das Durchlaufen aller Personen in der Organisation – liegen außerhalb des Bereichs von Mail-Apps. Da es sich außerdem um eine leistungsstarke unterstützte Vorgangsuntergruppe handelt, müssen Mail-Apps Lese-Schreibberechtigungen für das Postfach im App-Manifest anfordern, und nur Administratoren können Mail-Apps installieren, die diese Berechtigung benötigen.

Wenn Sie die Mailbox.makeEwsRequestAsync-Methode aufrufen, fordern Sie die Exchange-Webdienste auf dem Exchange-Server an, der das Postfach des Benutzers hostet. Legen Sie vor dem Aufrufen von „makeEwsRequestAsync“ Eingabeargumente für die folgenden Parameter fest:

  • data-Parameter: Erstellen Sie eine XML-SOAP-Anforderung für den Exchange-Webdienste-Vorgang, den Sie aufrufen möchten.
  • callback-Parameter: Eine Rückrufmethode zum Verarbeiten der Antwort aus dem Vorgang.
  • userContext-Parameter: Beliebige Eingabedaten für die Rückrufmethode.

Wenn der Vorgang beendet wird, ruft das Apps für Office-Framework die Rückrufmethode mit einem Argument auf, welches ein AsyncResult-Objekt ist, ähnlich wie bei den anderen asynchronen Methoden, denen Sie im ersten Teil dieser Reihe begegnet sind. Die Rückrufmethode kann auf die Async­Result.value-Eigenschaft zugreifen, um die XML-SOAP-Antwort abzurufen, welche die für den Vorgang relevanten Daten enthält. Die Rückrufmethode kann auch auf die AsyncResult.asyncContext-Eigenschaft zugreifen, um auf alle anderen Eingabeparameter zuzugreifen, die über den userContext-Parameter übergeben wurden. Anschließend verarbeitet die Rückrufmethode den XML-Code in der SOAP-Antwort, um die für ihre Zwecke relevanten Daten zu erhalten.

Eine vollständige Liste der unterstützten Vorgänge der Exchange-Webdienste und weitere Details finden Sie in der Dev Center-Dokumentation „Aufrufen von Webdiensten in einer Mail-App in Outlook“ (bit.ly/12jtH0z).

Ein Beispiel für eine Mail-App, das den Aufruf des GetItem-Vorgangs zeigt, finden Sie in C# für Visual Studio 2012 unter „Mail-Apps für Outlook: Ausführen einer Exchange-Webdienste-Anforderung“ (bit.ly/Zv3hEQ).

Zusammenfassung

Hiermit schließe ich meine Erläuterungen zur Erstellung von Mail-Apps und die vierteilige Betrachtung der JavaScript-API für Office ab. Die vorigen Teile der Reihe und den begleitenden Onlineartikel zu diesem Teil finden Sie unter folgenden Links:

Angela Chu-Hatoun begann als Softwareentwicklerin. Sie entfaltete großes Interesse daran, die Funktionsweise von Software zu erläutern, und wechselte daher zum Schreiben. Sie ist seit 12 Jahren in der Office Division als Programmiererin und Autorin tätig und schreibt für Entwickler über die Erstellung von Apps für Office und anderen Lösungen für Outlook. Angela Chu-Hatoun vertieft sich gerne in Lektüre über das Tagesgeschehen, Gartenarbeit, Reisen, Ernährung und Mode.

Unser Dank gilt den folgenden technischen Experten für die Durchsicht dieses Artikels: Andrew Salamatov (Microsoft) und Tim Wan (Microsoft)
Tim Wan hat 2003 sein Studium am California Institute of Technology (Caltech) mit einem Abschluss in Engineering and Applied Sciences beendet. In den letzten neun Jahren war er als Outlook-Softwareentwickler tätig. Er hat umfangreiche Arbeit am Mail-Apps-Feature in Outlook 2013 sowie am Outlook-Objektmodell in früheren Versionen geleistet. Tim Wan freut sich darauf, den Kunden weltweit neue Features und Verbesserungen zur Verfügung zu stellen.