Obtener y establecer encabezados de Internet en un mensaje en un complemento de Outlook

Los encabezados de Internet permiten que el complemento de Outlook adjunte datos de clave-valor personalizados a un mensaje saliente que persiste después de que el mensaje salga de Exchange. A diferencia de las propiedades personalizadas de nivel de elemento, los encabezados de Internet viajan con el correo electrónico, por lo que los complementos de los destinatarios pueden leerlos. En este artículo se muestra cómo establecer encabezados de Internet al redactar un mensaje y cómo leerlos de un mensaje recibido.

Por qué usar encabezados de Internet

Los complementos de Outlook pueden almacenar datos personalizados en distintos ámbitos.

• Nivel de elemento: use CustomProperties para los valores vinculados a un elemento entre sesiones o SessionData para los valores necesarios solo durante la sesión de redacción actual.
• Nivel de buzón: use RoamingSettings para los valores que se aplican en el buzón del usuario.

Estas opciones no se conservan en el mensaje después de salir de Exchange, por lo que los destinatarios no pueden leer esos valores. Los encabezados de Internet abordan esta limitación.

Introducidas en el conjunto de requisitos de buzón 1.8, las API de encabezados de Internet le permiten:

• Stamp information on an email that persists after it leaves Exchange across clients.
• Lee información persistente de un correo electrónico en escenarios de lectura entre clientes.
• Acceda al encabezado MIME completo del correo electrónico.

En entornos locales de Exchange, puede establecer encabezados de Internet a través de solicitudes de Servicios web de Exchange (EWS). Sin embargo, algunos escenarios pueden producir errores. Por ejemplo, en el modo de redacción en el escritorio de Outlook, el identificador de elemento no se sincroniza en saveAsync el modo almacenado en caché.

Clientes compatibles

Para usar la API de encabezados de Internet en el complemento, el cliente de Outlook debe admitir el conjunto de requisitos 1.8 o posterior. Para obtener información sobre los clientes admitidos, vea Compatibilidad con clientes de Outlook.

La API de encabezados de Internet también se admite en Outlook en Android y en iOS a partir de la versión 4.2405.0. Para obtener más información sobre las características admitidas en Outlook en dispositivos móviles, consulte API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Establecimiento de encabezados de Internet al redactar un mensaje

Use la propiedad item.internetHeaders para administrar los encabezados de Internet personalizados que coloca en el mensaje actual en Compose modo.

Ejemplo de configuración, obtención y eliminación de encabezados de Internet personalizados

En el ejemplo siguiente se muestra cómo establecer, obtener y quitar encabezados de Internet personalizados.

// 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"}
*/

Obtención de encabezados de Internet al leer un mensaje

Llame a item.getAllInternetHeadersAsync para obtener encabezados de Internet en el mensaje actual en modo de lectura.

Obtener preferencias del remitente del ejemplo actual de encabezados MIME

En el ejemplo de la sección anterior, el código siguiente muestra cómo obtener las preferencias del remitente de los encabezados MIME del correo electrónico actual.

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
*/

Procedimientos recomendados

Actualmente, los encabezados de Internet son un recurso finito en el buzón de un usuario. Cuando se agota la cuota, no se pueden crear más encabezados de Internet en ese buzón, lo que puede dar lugar a un comportamiento inesperado de los clientes que dependen de esto para funcionar.

Aplique las siguientes directrices al crear encabezados de Internet en el complemento.

• Cree el número mínimo de encabezados necesarios. La cuota de encabezado se basa en el tamaño total de los encabezados aplicados a un mensaje. En Exchange Online, el límite de encabezado se limita a 256 KB, mientras que en un entorno local de Exchange, el límite lo determina el administrador de la organización. Para obtener más información sobre los límites de encabezado, consulte Exchange Online límites de mensajes y Exchange Server límites de mensajes.
• Asigne un nombre a los encabezados para que pueda reutilizar y actualizar sus valores más adelante. Por lo tanto, evite asignar nombres a los encabezados de forma variable (por ejemplo, en función de la entrada del usuario, la marca de tiempo, etc.).

Vea también

• Obtener y establecer metadatos de un complemento de Outlook
• Límites de activación y uso de API en complementos de Outlook