Compartilhar via

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 seu suplemento do Outlook, mas cada método armazena os dados separadamente do outro. Ou seja, os dados armazenados através de definições de roaming não são acessíveis por propriedades personalizadas e vice-versa. As definições de roaming são armazenadas na caixa de correio do utilizador enquanto as propriedades personalizadas são armazenadas numa mensagem ou compromisso. Os dados armazenados são acessíveis nas sessões subsequentes do Outlook em todos os fatores de formulário suportados pelo suplemento.

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. Deve guardar explicitamente todas as definições de roaming depois de as atualizar para que fiquem disponíveis da próxima vez que o utilizador abrir o seu suplemento, no mesmo dispositivo ou em qualquer outro dispositivo suportado.

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).

Segue-se um exemplo da estrutura, partindo do princípio de que existem três definições de roaming definidas denominadas 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 seguinte exemplo de código JavaScript mostra como carregar definições de roaming existentes e obter os valores de duas definiçõ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 utilizar o método RoamingSettings.set para definir uma definição com o nome cookie com a data atual e manter os dados utilizando o método RoamingSettings.saveAsync para guardar todas as definições de roaming na caixa de correio do utilizador.

O set método cria a definição se a definição ainda não existir e atribui a definição ao valor especificado. O saveAsync método guarda as definições de roaming de forma assíncrona. Este exemplo de código transmite uma função de chamada de retorno, saveMyAddInSettingsCallback, para saveAsync. Quando a chamada assíncrona é concluída, saveMyAddInSettingsCallback é chamada através de 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

Também expandindo os exemplos anteriores, a seguinte função JavaScript, removeAddInSetting, mostra como utilizar o método RoamingSettings.remove para remover a cookie definição e guardar todas as definiçõ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. Isto garante que, se o utilizador voltar a abrir a mensagem, o seu suplemento de correio não se oferece 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 se certificar de que estas propriedades personalizadas estarão disponíveis na próxima sessão, utilize CustomProperties.saveAsync.

Estas propriedades personalizadas específicas do suplemento específico do item só podem ser acedidas com o CustomProperties objeto . Estas propriedades são diferentes das Propriedades de Utilizador personalizadas baseadas em MAPI no modelo de objetos do Outlook e propriedades expandidas nos Serviços Web exchange (EWS). Não pode aceder CustomProperties diretamente ao utilizar o modelo de objetos do Outlook, o EWS ou o REST. Para saber como aceder CustomProperties com o EWS ou REST, consulte a secção Obter propriedades personalizadas com o EWS ou REST.

Observação

As propriedades personalizadas só estão disponíveis para o suplemento que as criou e apenas através do item de correio no qual foram guardadas. Por este motivo, as propriedades definidas no modo de composição não são transmitidas aos destinatários do item de correio. Quando é enviada uma mensagem ou compromisso com propriedades personalizadas, as respetivas propriedades podem ser acedidas a partir do item na pasta Itens Enviados . Para permitir que os destinatários recebam os dados personalizados dos seus conjuntos de suplementos, considere antes utilizar InternetHeaders .

Usar propriedades personalizadas

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

Observação

Ao utilizar propriedades personalizadas nos suplementos do Outlook, tenha em atenção que:

  • O Outlook para Mac não coloca em cache propriedades personalizadas. Se a rede do utilizador ficar inativa, os suplementos no Outlook para Mac não poderão aceder às respetivas propriedades personalizadas.
  • No Outlook clássico no Windows, as propriedades personalizadas guardadas no modo de composição só persistem depois de o item ser composto ser fechado ou depois Office.context.mailbox.item.saveAsync de ser chamado.

Exemplo de propriedades personalizadas

O exemplo seguinte mostra um conjunto simplificado de funções e métodos para um suplemento do Outlook que utiliza 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 é devolvido do servidor e guarda-o localmente para utilização posterior.

  • updateProperty - Define ou atualiza uma propriedade específica e, em seguida, guarda a alteração no saco de propriedades local.

  • removeProperty – remove uma propriedade específica do saco de propriedades e, em seguida, guarda estas 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 às propriedades normais baseadas em MAPI. As APIs de suplemento serializam todos os suplementos CustomProperties como um payload JSON e, em seguida, guardam-nos numa única propriedade expandida baseada em MAPI cujo nome é cecp-<app-guid> (<app-guid> é o 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

O seu suplemento de correio pode obter a CustomProperties propriedade expandida baseada em MAPI com a operação GetItem do EWS. Aceda GetItem ao lado do servidor através de um token de chamada de retorno ou do lado do cliente com o método mailbox.makeEwsRequestAsync . GetItem No pedido, especifique a CustomProperties propriedade baseada em MAPI no conjunto de propriedades com os detalhes fornecidos na secção anterior Como as propriedades personalizadas são armazenadas num 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 nas mensagens

A tabela seguinte resume o comportamento das propriedades personalizadas guardadas nas mensagens de vários clientes do Outlook.

Cenário Outlook na Web e em novo cliente Windows Outlook clássico no Windows Outlook no Mac
Nova composição null null null
Responder, responder a todos null null null
Encaminhar null Carrega as propriedades do encarregado de educação null
Item enviado da nova composição null null null
Item enviado de resposta ou resposta a todos null null null
Item enviado a partir do reencaminhamento null Remove as propriedades do encarregado de educação se não forem guardadas null

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

  1. Verifique se existem propriedades ao inicializar o suplemento e mantenha-os ou limpe-os conforme necessário.
  2. Ao definir propriedades personalizadas, inclua uma propriedade adicional para indicar se as propriedades personalizadas foram adicionadas no modo de leitura. Isto irá ajudá-lo a diferenciar se a propriedade foi criada no modo de composição ou herdada do elemento principal.
  3. Para verificar se o utilizador está a reencaminhar ou a responder a uma mensagem, pode utilizar item.getComposeTypeAsync (disponível no requisito definido como 1.10).

Confira também