Obter e definir metadados de suplemento para um suplemento do Outlook

  • Artigo

Você pode gerenciar dados personalizados em seu suplemento do Outlook usando um destes procedimentos:

  • As configurações de roaming, que gerenciam dados personalizados para uma caixa de correio de usuário.
  • Propriedades personalizadas, que gerenciam dados personalizados para um item na caixa de correio do usuário.

Ambos dão acesso a dados personalizados que só são acessíveis pelo suplemento do Outlook, mas cada método armazena os dados separadamente do outro. Ou seja, os dados armazenados por meio de configurações de roaming não são acessíveis por propriedades personalizadas e vice-versa. As configurações de roaming são armazenadas na caixa de correio do usuário enquanto as propriedades personalizadas são armazenadas em uma mensagem ou compromisso. Os dados armazenados são acessíveis em sessões subsequentes do Outlook em todos os fatores de formulário que o suplemento dá suporte.

Dados personalizados por caixa de correio: configurações de roaming

Você pode especificar dados específicos para uma caixa de correio do Exchange de um usuário usando o objeto RoamingSettings. Exemplos desses dados incluem os dados pessoais e as preferências do usuário. O suplemento de email pode acessar as configurações de roaming quando faz roaming em qualquer dispositivo no qual deva ser executado (área de trabalho, tablet ou smartphone).

As mudanças nesses dados são armazenadas em uma cópia na memória dessas configurações para a sessão atual do Outlook. Você deve salvar explicitamente todas as configurações de roaming depois de atualizá-las para que elas estejam disponíveis na próxima vez que o usuário abrir seu suplemento, no mesmo ou em qualquer outro dispositivo com suporte.

Formato das configurações de roaming

Os dados de um objeto RoamingSettings são armazenados como uma cadeia de caracteres serializada JavaScript Object Notation (JSON).

A seguir está um exemplo da estrutura, supondo que haja três configurações de roaming definidas chamadas add-in_setting_name_0, add-in_setting_name_1e add-in_setting_name_2.

{
  "add-in_setting_name_0": "add-in_setting_value_0",
  "add-in_setting_name_1": "add-in_setting_value_1",
  "add-in_setting_name_2": "add-in_setting_value_2"
}

Carregar configurações de roaming

Um suplemento de email normalmente carrega configurações de roaming no manipulador de eventos Office.initialize. O exemplo de código JavaScript a seguir mostra como carregar as configurações de roaming existentes e obter os valores de duas configurações, customerName e customerBalance.

let _mailbox;
let _settings;
let _customerName;
let _customerBalance;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  // Initialize instance variables to access API objects.
  _mailbox = Office.context.mailbox;
  _settings = Office.context.roamingSettings;
  _customerName = _settings.get("customerName");
  _customerBalance = _settings.get("customerBalance");
}

Criar ou atribuir uma configuração de roaming

Continuando com o exemplo anterior, a seguinte função JavaScript, setAddInSetting, mostra como usar o método RoamingSettings.set para definir uma configuração nomeada cookie com a data de hoje e persistir os dados usando o método RoamingSettings.saveAsync para salvar todas as configurações de roaming na caixa de correio do usuário.

O set método cria a configuração se a configuração ainda não existir e atribui a configuração ao valor especificado. O saveAsync método salva as configurações de roaming de forma assíncrona. Este exemplo de código passa uma função de retorno de chamada, saveMyAddInSettingsCallbackpara saveAsync. Quando a chamada assíncrona é concluída, saveMyAddInSettingsCallback é chamada usando um parâmetro, asyncResult. Esse parâmetro é um objeto AsyncResult que contém o resultado e detalhes sobre a chamada assíncrona. Você pode usar o parâmetro opcional userContext para passar as informações de estado de chamada assíncrona à função de retorno de chamada.

// Set a roaming setting.
function setAddInSetting() {
  _settings.set("cookie", Date());
  // Save roaming settings to the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

// Callback function after saving custom roaming settings.
function saveMyAddInSettingsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Remover uma configuração móvel

Estendendo também os exemplos anteriores, a função JavaScript a seguir, removeAddInSetting, mostra como usar o método RoamingSettings.remove para remover a cookie configuração e salvar todas as configurações de roaming na caixa de correio.

// Remove an add-in setting.
function removeAddInSetting()
{
  _settings.remove("cookie");
  // Save changes to the roaming settings for the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

Dados personalizados por item em uma caixa de correio: propriedades personalizadas

Você pode especificar dados específicos de um item na caixa de correio do usuário usando o objeto CustomProperties. Por exemplo, seu suplemento de email poderia categorizar determinadas mensagens e anotar a categoria usando uma propriedade personalizada messageCategory. Ou, se seu suplemento de email cria compromissos de sugestões de reunião em uma mensagem, você pode usar uma propriedade personalizada para controlar cada um desses compromissos. Isso garante que, se o usuário abrir a mensagem novamente, seu suplemento de email não se oferecerá para criar o compromisso uma segunda vez.

Semelhante às configurações de roaming, as mudanças nas propriedades personalizadas são armazenadas em cópias na memória das propriedades para a sessão atual do Outlook. Para garantir que essas propriedades personalizadas estejam disponíveis na próxima sessão, use CustomProperties.saveAsync.

Essas propriedades personalizadas específicas do item e específicas do suplemento só podem ser acessadas usando o CustomProperties objeto. Essas propriedades são diferentes das UserProperties personalizadas baseadas em MAPI no modelo de objeto do Outlook e propriedades estendidas no Exchange Web Services (EWS). Você não pode acessar CustomProperties diretamente usando o modelo de objeto do Outlook, o EWS ou o REST. Para saber como acessar CustomProperties usando EWS ou REST, consulte a seção Obter propriedades personalizadas usando EWS ou REST.

Observação

As propriedades personalizadas só estão disponíveis para o suplemento que as criou e somente por meio do item de email no qual foram salvas. Por causa disso, as propriedades definidas enquanto estiverem no modo de composição não são transmitidas aos destinatários do item de email. Quando uma mensagem ou compromisso com propriedades personalizadas é enviada, suas propriedades podem ser acessadas a partir do item na pasta Itens Enviados . Para permitir que os destinatários recebam os dados personalizados de seus conjuntos de suplementos, considere usar InternetHeaders .

Usar propriedades personalizadas

Antes de poder usar propriedades personalizadas, você precisa carregá-las chamando o método loadCustomPropertiesAsync. Depois de criar o saco de propriedades, você pode usar o conjunto e obter métodos para adicionar e recuperar propriedades personalizadas. Você deve usar o saveAsync método para salvar as alterações feitas no conjunto de propriedades.

Observação

Ao usar propriedades personalizadas nos suplementos do Outlook, tenha em mente que:

  • O Outlook no Mac não armazena em cache propriedades personalizadas. Se a rede do usuário cair, os suplementos no Outlook no Mac não poderão acessar suas propriedades personalizadas.
  • No Outlook no Windows, as propriedades personalizadas salvas enquanto estiverem no modo de composição só persistem depois que o item que está sendo composto for fechado ou depois Office.context.mailbox.item.saveAsync for chamado.

Exemplo de propriedades personalizadas

O exemplo a seguir mostra um conjunto simplificado de funções e métodos para um suplemento do Outlook que usa propriedades personalizadas. Você pode usar este exemplo como ponto de partida para o seu suplemento que usa propriedades personalizadas.

Este exemplo inclui as seguintes funções e métodos.

  • Office.initialize: inicializa o suplemento e carrega o conjunto de propriedades personalizadas do Exchange Server.

  • customPropsCallback -- Obtém o saco de propriedades personalizado que é retornado do servidor e o salva localmente para uso posterior.

  • updateProperty -- define ou atualiza uma propriedade específica e salva a alteração no saco de propriedades local.

  • removeProperty -- Remove uma propriedade específica do saco de propriedades e, em seguida, salva essas alterações.

let _mailbox;
let _customProps;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  _mailbox = Office.context.mailbox;
  _mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
}

// Callback function from loading custom properties.
function customPropsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
  else {
    // Successfully loaded custom properties,
    // can get them from the asyncResult argument.
    _customProps = asyncResult.value;
  }
}

// Get individual custom property.
function getProperty() {
  const myProp = _customProps.get("myProp");
}

// Set individual custom property.
function updateProperty(name, value) {
  _customProps.set(name, value);
  // Save all custom properties to the mail item.
  _customProps.saveAsync(saveCallback);
}

// Remove a custom property.
function removeProperty(name) {
  _customProps.remove(name);
  // Save all custom properties to the mail item.
  _customProps.saveAsync(saveCallback);
}

// Callback function from saving custom properties.
function saveCallback() {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Obtenha propriedades personalizadas usando EWS ou REST

Para obter CustomProperties usando EWS ou restante, você deverá primeiro determinar o nome do seu MAPI baseado propriedade estendida. Você pode obter propriedade da mesma forma que você teria qualquer propriedade com base MAPI estendida.

Como as propriedades personalizadas são armazenadas em um item

As propriedades personalizadas definidas por um suplemento não são equivalentes a propriedades normais baseadas em MAPI. As APIs de suplemento serializam todos os suplementos CustomProperties como uma carga JSON e, em seguida, salvam-nas em uma única propriedade estendida baseada em MAPI cujo nome é (<app-guid> é cecp-<app-guid> a ID do suplemento) e o guid do conjunto de propriedades é {00020329-0000-0000-C000-000000000046}. (Para saber mais sobre esse objeto, confira MS-OXCEXT 2.2.5 propriedades personalizadas do aplicativo de e-mail.) Em seguida, você pode usar EWS ou REST para obter essa propriedade com base MAPI.

Obtenha propriedades personalizadas usando EWS

Seu suplemento de email pode obter a CustomProperties propriedade estendida baseada em MAPI usando a operação GetItem do EWS. Acesse GetItem no lado do servidor usando um token de retorno de chamada ou no lado do cliente usando o método mailbox.makeEwsRequestAsync . Na solicitação GetItem , especifique a CustomProperties propriedade baseada em MAPI em seu conjunto de propriedades usando os detalhes fornecidos na seção anterior Como as propriedades personalizadas são armazenadas em um item.

O exemplo a seguir mostra como acessar um item e suas propriedades personalizadas.

Importante

No exemplo a seguir, substituir <app-guid> com ID do suplemento.

let request_str =
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
                   'xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"' +
                   'xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"' +
                   'xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">' +
        '<soap:Header xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"' +
                     'xmlns:wsa="http://www.w3.org/2005/08/addressing">' +
            '<t:RequestServerVersion Version="Exchange2010_SP1"/>' +
        '</soap:Header>' +
        '<soap:Body>' +
            '<m:GetItem>' +
                '<m:ItemShape>' +
                    '<t:BaseShape>AllProperties</t:BaseShape>' +
                    '<t:IncludeMimeContent>true</t:IncludeMimeContent>' +
                    '<t:AdditionalProperties>' +
                        '<t:ExtendedFieldURI ' +
                          'DistinguishedPropertySetId="PublicStrings" ' +
                          'PropertyName="cecp-<app-guid>"' +
                          'PropertyType="String" ' +
                        '/>' +
                    '</t:AdditionalProperties>' +
                '</m:ItemShape>' +
                '<m:ItemIds>' +
                    '<t:ItemId Id="' +
                      Office.context.mailbox.item.itemId +
                    '"/>' +
                '</m:ItemIds>' +
            '</m:GetItem>' +
        '</soap:Body>' +
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(
    request_str,
    function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
            console.log(asyncResult.value);
        }
        else {
            console.log(JSON.stringify(asyncResult));
        }
    }
);

Você também pode obter mais propriedades personalizadas se especificar na cadeia de caracteres solicitação como outros ExtendedFieldURI elementos.

Obtenha propriedades personalizadas usando REST

No seu suplemento, você pode criar sua consulta REST para mensagens e eventos para obter as que já têm propriedades personalizadas. Em sua consulta, você deve incluir o CustomProperties propriedades de MAPI baseados na sua propriedade definida utilizando os detalhes fornecidos na seção como as propriedades personalizadas são armazenadas em um item.

O exemplo a seguir mostra como obter todos os eventos com as propriedades personalizadas definidos pelo seu suplemento e certifique-se que a resposta inclui o valor da propriedade para que você possa aplicar mais filtragem lógica.

Importante

No exemplo a seguir substituir <app-guid> com ID do suplemento.

GET https://outlook.office.com/api/v2.0/Me/Events?$filter=SingleValueExtendedProperties/Any
  (ep: ep/PropertyId eq 'String {00020329-0000-0000-C000-000000000046}
  Name cecp-<app-guid>' and ep/Value ne null)
  &$expand=SingleValueExtendedProperties($filter=PropertyId eq 'String
  {00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')

Outros exemplos que usam o REST para obter um único valor com base MAPI estendida, confira Obter singleValueExtendedProperty.

O exemplo a seguir mostra como acessar um item e suas propriedades personalizadas. Na função retorno de chamada para o done método item.SingleValueExtendedProperties contém uma lista das propriedades personalizadas solicitadas.

Importante

No exemplo a seguir, substituir <app-guid> com ID do suplemento.

Office.context.mailbox.getCallbackTokenAsync(
    {
        isRest: true
    },
    function (asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded
            && asyncResult.value !== "") {
            let item_rest_id = Office.context.mailbox.convertToRestId(
                Office.context.mailbox.item.itemId,
                Office.MailboxEnums.RestVersion.v2_0);
            let rest_url = Office.context.mailbox.restUrl +
                           "/v2.0/me/messages('" +
                           item_rest_id +
                           "')";
            rest_url += "?$expand=SingleValueExtendedProperties($filter=PropertyId eq 'String {00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')";

            let auth_token = asyncResult.value;
            $.ajax(
                {
                    url: rest_url,
                    dataType: 'json',
                    headers:
                        {
                            "Authorization":"Bearer " + auth_token
                        }
                }
                ).done(
                    function (item) {
                        console.log(JSON.stringify(item));
                    }
                ).fail(
                    function (error) {
                        console.log(JSON.stringify(error));
                    }
                );
        } else {
            console.log(JSON.stringify(asyncResult));
        }
    }
);

Comportamento da plataforma em mensagens

A tabela a seguir resume o comportamento de propriedades personalizadas salvas em mensagens para vários clientes do Outlook.

Cenário Outlook na Web e no novo cliente Windows (versão prévia) Outlook clássico no Windows Outlook no Mac
Novo compose null null null
Responder, responder tudo null null null
Encaminhar null Carrega as propriedades dos pais null
Item enviado do novo compose null null null
Enviar item de resposta ou responder a todos null null null
Item enviado de frente null Remove as propriedades dos pais se não forem salvas null

Para lidar com a situação no Outlook no Windows:

  1. Verifique se há propriedades existentes na inicialização do suplemento e mantenha-as ou desmarque-as conforme necessário.
  2. Ao definir propriedades personalizadas, inclua uma propriedade adicional para indicar se as propriedades personalizadas foram adicionadas no modo de leitura. Isso ajudará você a diferenciar se a propriedade foi criada no modo de composição ou herdada do pai.
  3. Para marcar se o usuário estiver encaminhando ou respondendo a uma mensagem, você poderá usar item.getComposeTypeAsync (disponível do conjunto de requisitos 1.10).

Confira também