Compartilhar via

Obter e definir cabeçalhos da Internet numa mensagem num suplemento do Outlook

  • Artigo

Histórico

Um requisito comum no desenvolvimento de suplementos do Outlook é armazenar propriedades personalizadas associadas a um suplemento em diferentes níveis. Atualmente, as propriedades personalizadas são armazenadas ao nível do item ou da caixa de correio.

  • Nível do item – para propriedades que se aplicam a um item específico que precisa de ser acedido durante as sessões subsequentes do Outlook, utilize o objeto CustomProperties . Por exemplo, armazene um código de cliente associado à pessoa que enviou o e-mail. Se as propriedades de um item específico só forem necessárias durante a sessão de composição atual, utilize o objeto SessionData .
  • Nível da caixa de correio – para propriedades que se aplicam a todos os itens de correio na caixa de correio do utilizador, utilize o objeto RoamingSettings . Por exemplo, armazene a preferência de um utilizador para mostrar a temperatura numa escala específica.

Estes tipos de propriedades não são preservados após o item sair do servidor Exchange, pelo que os destinatários do e-mail não podem obter quaisquer propriedades definidas no item. Por conseguinte, os programadores não podem aceder a essas definições ou a outras propriedades do Multipurpose Internet Mail Extensions (MIME) para permitir cenários de leitura melhores.

Em ambientes do Exchange no local, embora exista uma forma de definir os cabeçalhos de Internet através de pedidos de Serviços Web exchange (EWS), em alguns cenários, fazer um pedido EWS não funcionará. Por exemplo, no modo Compose no ambiente de trabalho do Outlook, o ID do item não é sincronizado saveAsync no modo em cache.

Dica

Para saber mais sobre como utilizar estas opções, consulte Obter e definir metadados de suplementos para um suplemento do Outlook.

Objetivo da API de cabeçalhos da Internet

Introduzidas no conjunto de requisitos da Caixa de Correio 1.8, as APIs de cabeçalhos da Internet permitem aos programadores:

  • Carimbar informações num e-mail que persiste depois de deixar o Exchange em todos os clientes.
  • Leia informações num e-mail que persistia após o e-mail deixar o Exchange em todos os clientes em cenários de leitura de correio.
  • Aceda a todo o cabeçalho MIME do e-mail.

Diagrama de cabeçalhos da Internet. Texto: o utilizador 1 envia um e-mail. O suplemento gere cabeçalhos de Internet personalizados enquanto o utilizador está a compor e-mails. O utilizador 2 recebe o e-mail. O suplemento obtém cabeçalhos da Internet a partir de e-mails recebidos e, em seguida, analisa e utiliza cabeçalhos personalizados.

Clientes com suporte

Para utilizar a API de cabeçalhos da Internet no seu suplemento, o cliente do Outlook tem de suportar o requisito definido como 1.8 ou posterior. Para obter informações sobre clientes suportados, consulte Suporte de cliente do Outlook.

A API de cabeçalhos da Internet também é suportada no Outlook para Android e no iOS a partir da Versão 4.2405.0. Para saber mais sobre as funcionalidades suportadas no Outlook em dispositivos móveis, consulte APIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Definir cabeçalhos da Internet ao compor uma mensagem

Utilize a propriedade item.internetHeaders para gerir os cabeçalhos de Internet personalizados que coloca na mensagem atual no modo Compose.

Exemplo de definição, obtenção e remoção de cabeçalhos de Internet personalizados

O exemplo seguinte mostra como definir, obter e remover cabeçalhos 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"}
*/

Obter cabeçalhos da Internet ao ler uma mensagem

Chame item.getAllInternetHeadersAsync para obter cabeçalhos da Internet na mensagem atual no modo de Leitura.

Obter preferências de remetente a partir do exemplo de cabeçalhos mime atuais

Com base no exemplo da secção anterior, o seguinte código mostra como obter as preferências do remetente a partir dos cabeçalhos MIME do e-mail atual.

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

Importante

Este exemplo funciona para casos simples. Para obter informações mais complexas (por exemplo, cabeçalhos de várias instâncias ou valores dobrados, conforme descrito em RFC 2822), experimente utilizar uma biblioteca de análise mime adequada.

Atualmente, os cabeçalhos da Internet são um recurso finito na caixa de correio de um utilizador. Quando a quota está esgotada, não pode criar mais cabeçalhos de Internet nessa caixa de correio, o que pode resultar num comportamento inesperado dos clientes que dependem disto para funcionar.

Aplique as seguintes diretrizes quando criar cabeçalhos de Internet no seu suplemento.

  • Crie o número mínimo de cabeçalhos necessário. A quota de cabeçalho baseia-se no tamanho total dos cabeçalhos aplicados a uma mensagem. No Exchange Online, o limite de cabeçalhos está limitado a 256 KB, enquanto num ambiente do Exchange no local, o limite é determinado pelo administrador da sua organização. Para obter mais informações sobre os limites de cabeçalho, veja Exchange Online limites de mensagens e Exchange Server limites de mensagens.
  • Cabeçalhos de nomes para que possa reutilizar e atualizar os respetivos valores mais tarde. Como tal, evite atribuir nomes a cabeçalhos de forma variável (por exemplo, com base na entrada do utilizador, carimbo de data/hora, etc.).

Confira também