Compartilhar via

Obter e definir metadados de suplemento para um suplemento do Outlook

  • Artigo

Faça a gestão de dados personalizados no seu suplemento do Outlook com definições de roaming, propriedades personalizadas ou dados de sessão. Estas opções 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.

A tabela seguinte fornece uma descrição geral das opções disponíveis para gerir dados personalizados nos suplementos do Outlook.

Opção dados personalizados Conjunto de requisitos mínimo Aplicável a Descrição
Configurações de roaming 1.1 Mailbox Gere dados personalizados na caixa de correio de um utilizador. O suplemento que define os dados personalizados pode aceder aos mesmos a partir de outros dispositivos suportados onde a caixa de correio do utilizador está configurada. Os dados armazenados são acessíveis nas sessões subsequentes do Outlook.
Propriedades personalizadas 1.1 Item de correio Gere dados personalizados de um item de correio na caixa de correio de um utilizador. O suplemento que define os dados personalizados pode aceder aos mesmos a partir do item de correio em dispositivos suportados onde a caixa de correio do utilizador está configurada. Os dados armazenados são acessíveis nas sessões subsequentes do Outlook.
Os dados da sessão 1.11 Item de correio Gere os dados personalizados de um item de correio na sessão atual do Outlook do utilizador. O suplemento que define os dados personalizados só pode aceder aos mesmos a partir do item de correio enquanto estão a ser compostos.

Observação

Para obter informações sobre os conjuntos de requisitos e os respetivos clientes suportados, veja Conjuntos de requisitos da API JavaScript do Outlook.

Para saber mais sobre cada opção de dados personalizados, selecione o separador aplicável.

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.

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

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.

Confira também