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.
Importante
Embora a API de suplemento do Outlook limite o acesso a estas definições apenas ao suplemento que as criou, estas definições não devem ser consideradas armazenamento seguro. Podem ser acedidos por outros serviços, como o Microsoft Graph. Não devem ser utilizadas para armazenar informações confidenciais, como credenciais de utilizador ou tokens de segurança.
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_1
e 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
Normalmente, um suplemento de correio carrega definições de roaming no processador Office.onReady . 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;
Office.onReady((info) => {
if (info.host === Office.HostType.Outlook) {
// 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. Em seguida, mantém os dados através do 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
Continuando a expandir o exemplo anterior, 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 Outlook session.
_settings.saveAsync(saveMyAddInSettingsCallback);
}
Experimente o exemplo de código no Script Lab
Para saber como criar e gerir um objeto RoamingSettings, obtenha o Script Lab do suplemento outlook e experimente o exemplo "Utilizar definições de suplementos". Para saber mais sobre o Script Lab, consulte Explorar a API JavaScript do Office usando o Script Lab.
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 através do modelo de objetos do Outlook, do EWS ou do Microsoft Graph. Para saber como aceder CustomProperties
com o Microsoft Graph ou o EWS, consulte a secção Obter propriedades personalizadas com o Microsoft Graph ou o EWS.
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.
Experimente o exemplo de código no Script Lab
Para saber como criar e gerir um objeto CustomProperties, obtenha o Script Lab do suplemento outlook e experimente o exemplo "Trabalhar com propriedades personalizadas de itens". Para saber mais sobre o Script Lab, consulte Explorar a API JavaScript do Office usando o Script Lab.
Obter propriedades personalizadas com o Microsoft Graph ou o EWS
Para obter CustomProperties com o Microsoft Graph ou o EWS, primeiro deve determinar o nome da respetiva propriedade expandida baseada em MAPI. Você pode obter propriedade da mesma forma que você teria qualquer propriedade com base MAPI estendida.
A utilização do Microsoft Graph ou do EWS depende se um suplemento está em execução num ambiente Exchange Online ou do Exchange no local.
Exchange Online
Em ambientes Exchange Online, o seu suplemento pode construir um pedido do Microsoft Graph em relação a mensagens e eventos para obter os que já têm propriedades personalizadas. No seu pedido, deve incluir a propriedade baseada em MAPI CustomProperties e o respetivo conjunto de propriedades com os detalhes fornecidos em Como as propriedades personalizadas são armazenadas num item.
O exemplo seguinte mostra como obter todos os eventos que tenham propriedades personalizadas definidas pelo seu suplemento. Também garante que a resposta inclui o valor da propriedade, para que possa aplicar mais lógica de filtragem.
Importante
No exemplo a seguir, substituir <app-guid>
com ID do suplemento.
GET https://graph.microsoft.com/v1.0/me/events?$filter=singleValueExtendedProperties/Any
(ep: ep/id eq 'String {00020329-0000-0000-C000-000000000046}
Name cecp-<app-guid>' and ep/value ne null)
&$expand=singleValueExtendedProperties($filter=id eq 'String
{00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')
Para obter outros exemplos que obtêm propriedades expandidas baseadas em MAPI de valor único, veja Obter singleValueLegacyExtendedProperty.
Exchange local
Em ambientes do Exchange no local, 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 em 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.
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 obter mais informações sobre este objeto, consulte MS-OXCEXT 2.2.5 Propriedades Personalizadas da Aplicação de Correio.) Em seguida, pode utilizar o Microsoft Grpah ou o EWS para obter esta propriedade baseada em MAPI.
A tabela seguinte resume o comportamento das propriedades personalizadas guardadas nas mensagens de vários clientes do Outlook.
Cenário |
Outlook na Web e no 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:
- Verifique se existem propriedades ao inicializar o suplemento e mantenha-os ou limpe-os conforme necessário.
- 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.
- Para marcar se o utilizador estiver a reencaminhar ou a responder a uma mensagem, pode utilizar item.getComposeTypeAsync (disponível a partir do requisito definido como 1.10).