Compartir a través de

Obtener y establecer metadatos de un complemento de Outlook

  • Artículo

Administre datos personalizados en el complemento de Outlook mediante la configuración móvil, las propiedades personalizadas o los datos de sesión. Estas opciones proporcionan acceso a datos personalizados a los que solo puede acceder el complemento de Outlook, pero cada método almacena los datos por separado del otro. Es decir, los datos almacenados a través de la configuración de itinerancia no son accesibles para las propiedades personalizadas y viceversa.

En la tabla siguiente se proporciona información general sobre las opciones disponibles para administrar datos personalizados en complementos de Outlook.

Opción de datos personalizados Conjunto de requisitos mínimos Se aplica a Descripción
Configuración de movilidad 1.1 Mailbox Administra los datos personalizados en el buzón de un usuario. El complemento que establece los datos personalizados puede acceder a ellos desde otros dispositivos compatibles donde está configurado el buzón del usuario. Los datos almacenados son accesibles en sesiones posteriores de Outlook.
Propiedades personalizadas 1.1 Elemento de correo Administra los datos personalizados de un elemento de correo en el buzón de un usuario. El complemento que establece los datos personalizados puede acceder a ellos desde el elemento de correo en los dispositivos compatibles donde está configurado el buzón del usuario. Los datos almacenados son accesibles en sesiones posteriores de Outlook.
Datos de sesión 1.11 Elemento de correo Administra los datos personalizados de un elemento de correo en la sesión actual de Outlook del usuario. El complemento que establece los datos personalizados solo puede tener acceso a ellos desde el elemento de correo mientras se componen.

Nota:

Para obtener información sobre los conjuntos de requisitos y sus clientes admitidos, consulte Conjuntos de requisitos de la API de JavaScript de Outlook.

Para obtener más información sobre cada opción de datos personalizados, seleccione la pestaña aplicable.

Puede especificar los datos específicos del buzón de Exchange de un usuario mediante el objeto RoamingSettings. Los datos personales y las preferencias del usuario son ejemplos de estos datos. El complemento de correo puede obtener acceso a la configuración de movilidad cuando se mueve en cualquier dispositivo en el que pueda ejecutarse por diseño (escritorio, tableta o smartphone).

Los cambios en estos datos se almacenan en una copia en memoria de los parámetros de la sesión actual de Outlook. Debe guardar explícitamente todas las opciones de itinerancia después de actualizarlas para que estén disponibles la próxima vez que el usuario abra el complemento, en el mismo dispositivo o en cualquier otro dispositivo compatible.

Importante

Aunque la API del complemento de Outlook limita el acceso a esta configuración solo al complemento que las creó, esta configuración no debe considerarse almacenamiento seguro. Otros servicios pueden acceder a ellos, como Microsoft Graph. No deben usarse para almacenar información confidencial, como credenciales de usuario o tokens de seguridad.

Formato de las configuraciones de movilidad

Los datos de un objeto RoamingSettings se almacenan como una cadena serializada de notación de objetos JavaScript (JSON).

A continuación se muestra un ejemplo de la estructura, suponiendo que hay tres configuraciones de itinerancia definidas denominadas add-in_setting_name_0, add-in_setting_name_1y 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"
}

Carga de la configuración de movilidad

Un complemento de correo normalmente carga la configuración de itinerancia en el controlador Office.onReady . En el siguiente ejemplo de código de JavaScript se muestra cómo cargar la configuración de itinerancia existente y obtener los valores de dos configuraciones, customerName y 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");
  }
});

Creación o asignación de una configuración de movilidad

Continuando con el ejemplo anterior, la siguiente función de JavaScript, setAddInSetting, muestra cómo usar el método RoamingSettings.set para establecer una configuración denominada cookie con la fecha de hoy. A continuación, conserva los datos mediante el método RoamingSettings.saveAsync para guardar toda la configuración de itinerancia en el buzón del usuario.

El set método crea la configuración si la configuración aún no existe y asigna la configuración al valor especificado. El saveAsync método guarda la configuración de itinerancia de forma asincrónica. Este ejemplo de código pasa una función de devolución de llamada, saveMyAddInSettingsCallback, a saveAsync. Cuando finaliza la llamada asincrónica, saveMyAddInSettingsCallback se llama a mediante un parámetro, asyncResult. Este parámetro es un objeto AsyncResult que contiene el resultado de la llamada asíncrona y los detalles de la misma. Si lo desea, puede usar el parámetro opcional userContext para pasar la información de estado de la llamada asincrónica a la función de devolución de llamada.

// 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.
  }
}

Supresión de la configuración de movilidad

Al extender el ejemplo anterior, la siguiente función de JavaScript, removeAddInSetting, muestra cómo usar el método RoamingSettings.remove para quitar la cookie configuración y guardar toda la configuración de itinerancia en el buzón.

// 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);
}

Pruebe el ejemplo de código en Script Lab

Para obtener información sobre cómo crear y administrar un objeto RoamingSettings, obtenga el Script Lab para el complemento de Outlook y pruebe el ejemplo "Usar configuración de complemento". Para más información sobre Script Lab, consulte Explorar las API de JavaScript de Office con Script Lab.

Vea también