Abrufen und Festlegen von Internetheadern für eine Nachricht in einem Outlook-Add-In

Internetheader ermöglichen es Ihrem Outlook-Add-In, benutzerdefinierte Schlüssel-Wert-Daten an eine ausgehende Nachricht anzufügen, die beibehalten wird, nachdem die Nachricht Exchange verlassen hat. Im Gegensatz zu benutzerdefinierten Eigenschaften auf Elementebene werden Internetheader mit der E-Mail übertragen, sodass die Add-Ins der Empfänger sie lesen können. In diesem Artikel wird gezeigt, wie Internetheader beim Verfassen einer Nachricht festgelegt und aus einer empfangenen Nachricht gelesen werden.

Gründe für die Verwendung von Internetheadern

Outlook-Add-Ins können benutzerdefinierte Daten in verschiedenen Bereichen speichern.

• Elementebene: Verwenden Sie CustomProperties für Werte, die sitzungsübergreifend an ein Element gebunden sind, oder SessionData für Werte, die nur während der aktuellen Erstellungssitzung benötigt werden.
• Postfachebene: Verwenden Sie RoamingSettings für Werte, die für das Postfach des Benutzers gelten.

Diese Optionen bleiben in der Nachricht nicht erhalten, nachdem sie Exchange verlassen hat, sodass Empfänger diese Werte nicht lesen können. Internetheader beheben diese Einschränkung.

Die in Postfachanforderungssatz 1.8 eingeführten Internetheader-APIs ermöglichen Folgendes:

• Stempelinformationen für eine E-Mail, die beibehalten werden, nachdem sie Exchange clientübergreifend verlassen hat.
• Lesen persistenter Informationen aus einer E-Mail in clientübergreifenden Leseszenarien.
• Greifen Sie auf den vollständigen MIME-Header der E-Mail zu.

In lokalen Exchange-Umgebungen können Sie Internetheader über EwS-Anforderungen (Exchange-Webdienste) festlegen. Einige Szenarien können jedoch fehlschlagen. Im Verfassenmodus auf Dem Outlook-Desktop wird die Element-ID beispielsweise nicht im Zwischenspeichermodus synchronisiert saveAsync .

Unterstützte Clients

Um die Internetheader-API in Ihrem Add-In verwenden zu können, muss Ihr Outlook-Client den Anforderungssatz 1.8 oder höher unterstützen. Informationen zu unterstützten Clients finden Sie unter Outlook-Clientunterstützung.

Die Internetheader-API wird ab Version 4.2405.0 auch in Outlook unter Android und unter iOS unterstützt. Weitere Informationen zu features, die in Outlook auf mobilen Geräten unterstützt werden, finden Sie unter Outlook JavaScript-APIs, die in Outlook auf mobilen Geräten unterstützt werden.

Festlegen von Internetheadern beim Verfassen einer Nachricht

Verwenden Sie die item.internetHeaders-Eigenschaft, um die benutzerdefinierten Internetheader zu verwalten, die Sie in der aktuellen Nachricht im Compose Modus platzieren.

Beispiel für festlegen, abrufen und entfernen von benutzerdefinierten Internetheadern

Das folgende Beispiel zeigt, wie Sie benutzerdefinierte Internetheader festlegen, abrufen und entfernen.

// Set custom internet headers.
function setCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.setAsync(
    { "preferred-fruit": "orange", "preferred-vegetable": "broccoli", "best-vegetable": "spinach" },
    setCallback
  );
}

function setCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully set headers");
  } else {
    console.log("Error setting headers: " + JSON.stringify(asyncResult.error));
  }
}

// Get custom internet headers.
function getSelectedCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.getAsync(
    ["preferred-fruit", "preferred-vegetable", "best-vegetable", "nonexistent-header"],
    getCallback
  );
}

function getCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Selected headers: " + JSON.stringify(asyncResult.value));
  } else {
    console.log("Error getting selected headers: " + JSON.stringify(asyncResult.error));
  }
}

// Remove custom internet headers.
function removeSelectedCustomHeaders() {
  Office.context.mailbox.item.internetHeaders.removeAsync(
    ["best-vegetable", "nonexistent-header"],
    removeCallback);
}

function removeCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed selected headers");
  } else {
    console.log("Error removing selected headers: " + JSON.stringify(asyncResult.error));
  }
}

setCustomHeaders();
getSelectedCustomHeaders();
removeSelectedCustomHeaders();
getSelectedCustomHeaders();

/* Sample output:
Successfully set headers
Selected headers: {"best-vegetable":"spinach","preferred-fruit":"orange","preferred-vegetable":"broccoli"}
Successfully removed selected headers
Selected headers: {"preferred-fruit":"orange","preferred-vegetable":"broccoli"}
*/

Abrufen von Internetheadern beim Lesen einer Nachricht

Rufen Sie item.getAllInternetHeadersAsync auf, um Internetheader für die aktuelle Nachricht im Lesemodus abzurufen.

Beispiel zum Abrufen von Absendereinstellungen aus aktuellen MIME-Headern

Aufbauend auf dem Beispiel aus dem vorherigen Abschnitt zeigt der folgende Code, wie die Einstellungen des Absenders aus den MIME-Headern der aktuellen E-Mail abgerufen werden.

Office.context.mailbox.item.getAllInternetHeadersAsync(getCallback);

function getCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Sender's preferred fruit: " + asyncResult.value.match(/preferred-fruit:.*/gim)[0].slice(17));
    console.log("Sender's preferred vegetable: " + asyncResult.value.match(/preferred-vegetable:.*/gim)[0].slice(21));
  } else {
    console.log("Error getting preferences from header: " + JSON.stringify(asyncResult.error));
  }
}

/* Sample output:
Sender's preferred fruit: orange
Sender's preferred vegetable: broccoli
*/

Empfohlene Vorgehensweise

Derzeit sind Internetheader eine begrenzte Ressource im Postfach eines Benutzers. Wenn das Kontingent aufgebraucht ist, können Sie keine weiteren Internetheader für dieses Postfach erstellen, was zu unerwartetem Verhalten von Clients führen kann, die diese Funktion nutzen.

Wenden Sie die folgenden Richtlinien an, wenn Sie Internetheader in Ihrem Add-In erstellen.

• Erstellen Sie die mindest erforderliche Anzahl von Headern. Das Headerkontingent basiert auf der Gesamtgröße der Header, die auf eine Nachricht angewendet werden. In Exchange Online ist der Headergrenzwert auf 256 KB begrenzt, während in einer lokalen Exchange-Umgebung der Grenzwert vom Administrator Ihres organization festgelegt wird. Weitere Informationen zu Headergrenzwerten finden Sie unter Exchange Online Nachrichtengrenzwerte und Exchange Server Nachrichtengrenzwerte.
• Benennen Sie Header, damit Sie ihre Werte später wiederverwenden und aktualisieren können. Vermeiden Sie daher eine variable Benennung von Headern (z. B. basierend auf Benutzereingaben, Zeitstempeln usw.).

Siehe auch

• Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-In
• Einschränkungen für die Aktivierung und die API-Verwendung in Outlook-Add-Ins