Office. Mailbox interface

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

La aplicación debe tener el permiso de elemento de lectura especificado en su manifiesto para llamar al ewsUrl miembro en modo de lectura.
En el modo de redacción, debe llamar al saveAsync método antes de poder usar el ewsUrl miembro. La aplicación debe tener permisos de elemento de lectura y escritura para llamar al saveAsync método .
Esta propiedad no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.
El valor ewsUrl puede usarse por un servicio remoto para realizar llamadas EWS al buzón del usuario. Por ejemplo, puede crear un servicio remoto para obtener datos adjuntos del elemento seleccionado.

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

item

Elemento de buzón de correo. Dependiendo del contexto en el que se abra el complemento, el tipo de elemento puede variar. Si desea ver IntelliSense solo para un tipo o modo específico, convierta este elemento en uno de los siguientes:

Importante:

Al llamar a Office.context.mailbox.item en un mensaje, tenga en cuenta que el panel de lectura del cliente de Outlook debe estar activado. Para obtener instrucciones sobre cómo configurar el panel de lectura, consulte Uso y configuración del panel de lectura para obtener una vista previa de los mensajes.
item puede ser null si el complemento admite el anclaje del panel de tareas. Para obtener más información sobre cómo controlar, vea Implementar un panel de tareas anclable en Outlook.

item?: Item & ItemCompose & ItemRead & Message & MessageCompose & MessageRead & Appointment & AppointmentCompose & AppointmentRead;

Valor de propiedad

Office.Item & Office.ItemCompose & Office.ItemRead & Office.Message & Office.MessageCompose & Office.MessageRead & Office.Appointment & Office.AppointmentCompose & Office.AppointmentRead

masterCategories

Obtiene un objeto que proporciona métodos para administrar la lista maestra de categorías asociada a un buzón.

masterCategories: MasterCategories;

Valor de propiedad

Office.MasterCategories

Comentarios

[ Conjunto de API: Buzón 1.8 ]

Nivel mínimo de permiso: buzón de lectura y escritura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Master categories:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories in the master list.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const masterCategoriesToAdd = [
  {
    displayName: "TestCategory",
    color: Office.MailboxEnums.CategoryColor.Preset0
  }
];

Office.context.mailbox.masterCategories.addAsync(masterCategoriesToAdd, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully added categories to master list");
  } else {
    console.log("masterCategories.addAsync call failed with error: " + asyncResult.error.message);
  }
});

...

const masterCategoriesToRemove = ["TestCategory"];

Office.context.mailbox.masterCategories.removeAsync(masterCategoriesToRemove, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed categories from master list");
  } else {
    console.log("masterCategories.removeAsync call failed with error: " + asyncResult.error.message);
  }
});

restUrl

Obtiene la URL del punto de conexión REST para esta cuenta de correo electrónico.

restUrl: string;

Valor de propiedad

string

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

Los puntos de conexión REST v2.0 y beta de Outlook ahora están en desuso. Sin embargo, los complementos hospedados en AppSource y de publicación privada pueden usar el servicio REST hasta que finalice el soporte extendido para Outlook 2019 el 14 de octubre de 2025. El tráfico de estos complementos se identifica automáticamente para la exención. Esta exención también se aplica a los nuevos complementos desarrollados a partir del 31 de marzo de 2024. Aunque los complementos pueden usar el servicio REST hasta 2025, le recomendamos encarecidamente que migre los complementos para usar Microsoft Graph. Para obtener instrucciones, consulte Comparación de puntos de conexión de LA API REST de Microsoft Graph y Outlook.
El complemento debe tener el permiso de elemento de lectura especificado en su manifiesto para llamar al restUrl miembro en modo de lectura.
En el modo de redacción debe llamar al método saveAsync antes de poder usar el miembro restUrl. El complemento debe tener permisos de elemento de lectura y escritura para llamar al saveAsync método . Sin embargo, en escenarios de delegación o compartidos, en su lugar debe usar la targetRestUrl propiedad del objeto SharedProperties (introducida en el conjunto de requisitos 1.8). Para obtener más información, consulte el artículo carpetas compartidas y buzón compartido .

Ejemplos

// Get the URL of the REST endpoint.
const restUrl = Office.context.mailbox.restUrl;
console.log(`REST API URL: ${restUrl}`);

userProfile

Información sobre el usuario asociado al buzón de correo. Esto incluye el tipo de cuenta, el nombre para mostrar, la dirección de correo electrónico y la zona horaria.

Más información en Office.UserProfile

userProfile: UserProfile;

Valor de propiedad

Office.UserProfile

Detalles del método

addHandlerAsync(eventType, handler, options, callback)

Agrega un controlador de eventos para un evento admitido. Nota: Los eventos solo están disponibles con la implementación del panel de tareas.

Para ver los eventos admitidos, consulte la sección Eventos del modelo de objetos de buzón.

addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

eventType: Office.EventType | string

El evento que debe invocar el controlador.

handler: any

La función que va a controlar el evento. La función debe aceptar un único parámetro, que es un literal de objeto. La type propiedad del parámetro coincidirá con el eventType parámetro pasado a addHandlerAsync.

options: Office.AsyncContextOptions

Proporciona una opción para conservar los datos de contexto de cualquier tipo, sin cambios, para su uso en una devolución de llamada.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro de tipo Office.AsyncResult.

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

function loadNewItem(eventArgs) {
    const item = Office.context.mailbox.item;

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

addHandlerAsync(eventType, handler, callback)

Agrega un controlador de eventos para un evento admitido. Nota: Los eventos solo están disponibles con la implementación del panel de tareas.

Para ver los eventos admitidos, consulte la sección Eventos del modelo de objetos de buzón.

addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

eventType: Office.EventType | string

El evento que debe invocar el controlador.

handler: any

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro de tipo Office.AsyncResult.

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

convertToEwsId(id, restVersion)

Convierte un identificador admitido en el formato de servicios web de Exchange (EWS).

convertToEwsId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Parámetros

id: string

Identificador que se va a convertir en formato EWS. Esta cadena puede ser un identificador de elemento con formato para las API REST de Outlook o un identificador de conversación recuperado de Office.context.mailbox.item.conversationId.

restVersion: Office.MailboxEnums.RestVersion | string

Un valor que indica la versión de la API de REST de Outlook que se usa para recuperar el identificador de elemento.

Devoluciones

string

Comentarios

[ Conjunto de API: Buzón 1.3 ]

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Importante:

En octubre de 2024, los tokens heredados de identidad de usuario y devolución de llamada de Exchange se desactivarán de forma predeterminada para todos los inquilinos de Exchange Online. Esto forma parte de la Iniciativa de futuro seguro de Microsoft, que proporciona a las organizaciones las herramientas necesarias para responder al panorama actual de amenazas. Los tokens de identidad de usuario de Exchange seguirán funcionando para Exchange local. La autenticación de aplicaciones anidadas es el enfoque recomendado para los tokens en el futuro. Para obtener más información, consulte nuestra entrada de blog y página de preguntas más frecuentes.
Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.
Los identificadores de elemento recuperados a través de una API REST (como Microsoft Graph) usan un formato diferente al que usa EWS. El método convertToEwsId convierte un identificador con formato REST al formato adecuado para EWS.

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToLocalClientTime(timeValue)

Obtiene un diccionario con información de tiempo en el tiempo del cliente local.

La zona horaria usada por el cliente de Outlook varía según la plataforma. Outlook en Windows (clásico) y en Mac usan la zona horaria del equipo cliente. Outlook en la Web y la nueva Outlook en Windows usan la zona horaria establecida en el Centro de Administración de Exchange (EAC). Debería tratar los valores de fecha y hora de modo que los valores que aparezcan en la interfaz de usuario sean siempre coherentes con la zona horaria que el usuario espera.

En Outlook en Windows (clásico) y en Mac, el convertToLocalClientTime método devuelve un objeto de diccionario con los valores establecidos en la zona horaria del equipo cliente. En Outlook en la Web y nueva Outlook en Windows, el convertToLocalClientTime método devuelve un objeto de diccionario con los valores establecidos en la zona horaria especificada en el EAC.

convertToLocalClientTime(timeValue: Date): LocalClientTime;

Parámetros

timeValue: Date

Objeto Date .

Devoluciones

Office.LocalClientTime

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

convertToRestId(id, restVersion)

Convierte un identificador admitido en formato REST.

convertToRestId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Parámetros

id: string

Identificador que se va a convertir en formato REST. Esta cadena puede ser un identificador de elemento con formato para EWS que normalmente se recupera de Office.context.mailbox.item.itemId, un identificador de conversación recuperado deOffice.context.mailbox.item.conversationId o un identificador de serie recuperado deOffice.context.mailbox.item.seriesId .

restVersion: Office.MailboxEnums.RestVersion | string

Valor que indica la versión de la API REST de Outlook usada con el identificador convertido.

Devoluciones

string

Comentarios

[ Conjunto de API: Buzón 1.3 ]

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Importante:

Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.
Los identificadores de elemento recuperados a través de Exchange Web Services (EWS) o a través de la itemId propiedad usan un formato diferente al que usan las API REST (como Microsoft Graph). El método convertToRestId convierte un identificador con formato EWS al formato adecuado para REST.

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToUtcClientTime(input)

Obtiene un Date objeto de un diccionario que contiene información de hora.

El convertToUtcClientTime método convierte un diccionario que contiene una fecha y hora locales en un Date objeto con los valores correctos para la fecha y hora locales.

convertToUtcClientTime(input: LocalClientTime): Date;

Parámetros

input: Office.LocalClientTime

El valor de la hora local para convertir.

Devoluciones

Date

Objeto Date con el tiempo expresado en UTC.

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// Represents 3:37 PM PDT on Monday, August 26, 2019.
const input = {
    date: 26,
    hours: 15,
    milliseconds: 2,
    minutes: 37,
    month: 7,
    seconds: 2,
    timezoneOffset: -420,
    year: 2019
};

// result should be a Date object.
const result = Office.context.mailbox.convertToUtcClientTime(input);

// Output should be "2019-08-26T22:37:02.002Z".
console.log(result.toISOString());

displayAppointmentForm(itemId)

Muestra una cita de calendario existente.

El displayAppointmentForm método abre una cita de calendario existente en una nueva ventana del escritorio.

En Outlook en Mac, puede usar este método para mostrar una sola cita que no forme parte de una serie periódica o la cita maestra de una serie periódica. Sin embargo, no se puede mostrar una instancia de la serie porque no se puede acceder a las propiedades (incluido el identificador de elemento) de las instancias de una serie periódica.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica una cita existente, se abre un panel en blanco en el equipo o dispositivo cliente y no se devuelve ningún mensaje de error.

displayAppointmentForm(itemId: string): void;

Parámetros

itemId: string

Identificador de los servicios web de Exchange (EWS) para una cita de calendario existente.

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante: Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = $("#itemId").val();
Office.context.mailbox.displayAppointmentForm(itemId);

displayAppointmentFormAsync(itemId, options, callback)

Muestra una cita de calendario existente.

El método displayAppointmentFormAsync abre una cita de calendario existente en una nueva ventana del escritorio o en un cuadro de diálogo en los dispositivos móviles.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica una cita existente, se abre un panel en blanco en el equipo o dispositivo cliente y no se devuelve ningún mensaje de error.

Nota: Este método no se admite en Outlook en iOS ni en Android.

displayAppointmentFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

itemId: string

Identificador de los servicios web de Exchange (EWS) para una cita de calendario existente.

options: Office.AsyncContextOptions

Literal de objeto que contiene una o varias de las siguientes propiedades:- asyncContext: los desarrolladores pueden proporcionar cualquier objeto al que quieran acceder en la función de devolución de llamada.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto .

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = $("#itemId").val();

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayAppointmentFormAsync(itemId, function(asyncResult) {
  console.log("Result: " + JSON.stringify(asyncResult));
});

displayAppointmentFormAsync(itemId, callback)

Muestra una cita de calendario existente.

El método displayAppointmentFormAsync abre una cita de calendario existente en una nueva ventana del escritorio o en un cuadro de diálogo en los dispositivos móviles.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica una cita existente, se abre un panel en blanco en el equipo o dispositivo cliente y no se devuelve ningún mensaje de error.

Nota: Este método no se admite en Outlook en iOS ni en Android.

displayAppointmentFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

itemId: string

Identificador de los servicios web de Exchange (EWS) para una cita de calendario existente.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto .

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

displayMessageForm(itemId)

Muestra un mensaje existente.

El displayMessageForm método abre un mensaje existente en una nueva ventana del escritorio.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica un mensaje existente, no se mostrará ningún mensaje en el equipo cliente y no se devolverá ningún mensaje de error.

displayMessageForm(itemId: string): void;

Parámetros

itemId: string

Identificador de los servicios web de Exchange (EWS) para un mensaje existente.

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.
No use displayMessageForm con un itemId que represente una cita. Use el método displayAppointmentForm para mostrar una cita existente y displayNewAppointmentForm para mostrar un formulario para crear una cita nueva.

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = $("#itemId").val();
Office.context.mailbox.displayMessageForm(itemId);

displayMessageFormAsync(itemId, options, callback)

Muestra un mensaje existente.

El método displayMessageFormAsync abre un mensaje existente en una nueva ventana del escritorio o en un cuadro de diálogo en los dispositivos móviles.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica un mensaje existente, no se mostrará ningún mensaje en el equipo cliente y no se devolverá ningún mensaje de error.

No use el displayMessageForm método o displayMessageFormAsync con un itemId que represente una cita. Use el displayAppointmentForm método o displayAppointmentFormAsync para mostrar una cita existente o displayNewAppointmentFormdisplayNewAppointmentFormAsync para mostrar un formulario para crear una cita.

Nota: Este método no se admite en Outlook en iOS ni en Android.

displayMessageFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

itemId: string

Identificador de los servicios web de Exchange (EWS) para un mensaje existente.

options: Office.AsyncContextOptions

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto .

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = $("#itemId").val();

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayMessageFormAsync(itemId, function (asyncResult) {
 console.log("Result: " + JSON.stringify(asyncResult));
});

displayMessageFormAsync(itemId, callback)

Muestra un mensaje existente.

El método displayMessageFormAsync abre un mensaje existente en una nueva ventana del escritorio o en un cuadro de diálogo en los dispositivos móviles.

En Outlook en la Web y nueva Outlook en Windows, este método abre el formulario especificado solo si el cuerpo del formulario es menor o igual que 32 000 caracteres.

Si el identificador de elemento especificado no identifica un mensaje existente, no se mostrará ningún mensaje en el equipo cliente y no se devolverá ningún mensaje de error.

Nota: Este método no se admite en Outlook en iOS ni en Android.

displayMessageFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

itemId: string

Identificador de los servicios web de Exchange (EWS) para un mensaje existente.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto .

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

displayNewAppointmentForm(parameters)

Muestra un formulario para crear una cita de calendario.

El método displayNewAppointmentForm abre un formulario que permite al usuario crear una nueva cita o reunión. Si se especifican parámetros, los campos de formulario de cita se rellenan automáticamente con el contenido de los parámetros.

En Outlook en la Web y nueva Outlook en Windows, este método siempre muestra un formulario con un campo de asistentes. Si no especifica ningún asistente como argumentos de entrada, el método muestra un formulario con un botón Guardar . Si ha especificado asistentes, el formulario incluirá a los asistentes y un botón Enviar.

En Outlook en Windows (clásico) y en Mac, si especifica asistentes o recursos en el requiredAttendeesparámetro , optionalAttendeeso resources , este método muestra un formulario de reunión con un botón Enviar . Si no se especifica ningún destinatario, este método muestra un formulario de cita con un botón Guardar y cerrar.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

displayNewAppointmentForm(parameters: AppointmentForm): void;

Parámetros

parameters: Office.AppointmentForm

que AppointmentForm describe la nueva cita. Todas las propiedades son opcionales.

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

Office.context.mailbox.displayNewAppointmentForm({
  requiredAttendees: ["bob@contoso.com"],
  optionalAttendees: ["sam@contoso.com"],
  start: start,
  end: end,
  location: "Home",
  subject: "meeting",
  resources: ["projector@contoso.com"],
  body: "Hello World!"
});

displayNewAppointmentFormAsync(parameters, options, callback)

Muestra un formulario para crear una cita de calendario.

El método displayNewAppointmentFormAsync abre un formulario que permite al usuario crear una nueva cita o reunión. Si se especifican parámetros, los campos de formulario de cita se rellenan automáticamente con el contenido de los parámetros.

En Outlook en la Web y nueva Outlook en Windows, este método siempre muestra un formulario con un campo de asistentes. Si no especifica ningún asistente como argumento de entrada, el método muestra un formulario con un botón Guardar. Si ha especificado asistentes, el formulario incluirá a los asistentes y un botón Enviar.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

Nota: Este método no se admite en Outlook en iOS ni en Android.

displayNewAppointmentFormAsync(parameters: AppointmentForm, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

parameters: Office.AppointmentForm

que AppointmentForm describe la nueva cita. Todas las propiedades son opcionales.

options: Office.AsyncContextOptions

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto .

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new appointment form has been created.
Office.context.mailbox.displayNewAppointmentFormAsync(
  {
    requiredAttendees: ["bob@contoso.com"],
    optionalAttendees: ["sam@contoso.com"],
    start: start,
    end: end,
    location: "Home",
    subject: "meeting",
    resources: ["projector@contoso.com"],
    body: "Hello World!"
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewAppointmentFormAsync(parameters, callback)

Muestra un formulario para crear una cita de calendario.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

Nota: Este método no se admite en Outlook en iOS ni en Android.

displayNewAppointmentFormAsync(parameters: AppointmentForm, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

parameters: Office.AppointmentForm

que AppointmentForm describe la nueva cita. Todas las propiedades son opcionales.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto .

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

displayNewMessageForm(parameters)

Muestra un formulario para crear un mensaje.

El displayNewMessageForm método abre un formulario que permite al usuario crear un nuevo mensaje. Si se especifican parámetros, los campos del formulario del mensaje se rellenan automáticamente con el contenido de los parámetros.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

displayNewMessageForm(parameters: any): void;

Parámetros

parameters: any

Diccionario que contiene todos los valores que se van a rellenar para el usuario en el nuevo formulario. Todos los parámetros son opcionales.

toRecipients : matriz de cadenas que contienen las direcciones de correo electrónico o una matriz que contiene un objeto EmailAddressDetails para cada uno de los destinatarios de la línea To . La matriz está limitada a un máximo de 100 entradas.

ccRecipients : matriz de cadenas que contienen las direcciones de correo electrónico o una matriz que contiene un objeto EmailAddressDetails para cada uno de los destinatarios de la línea Cc . La matriz está limitada a un máximo de 100 entradas.

bccRecipients : matriz de cadenas que contienen las direcciones de correo electrónico o una matriz que contiene un objeto EmailAddressDetails para cada uno de los destinatarios de la línea CCO . La matriz está limitada a un máximo de 100 entradas.

subject : cadena que contiene el asunto del mensaje. La cadena está limitada a un máximo de 255 caracteres.

htmlBody : el cuerpo HTML del mensaje. El contenido del cuerpo está limitado a un tamaño máximo de 32 KB.

attachments : matriz de objetos JSON que son datos adjuntos de archivos o elementos.

attachments.type : indica el tipo de datos adjuntos. Debe ser file para un archivo adjunto o item para un elemento adjunto.

attachments.name : cadena que contiene el nombre de los datos adjuntos, de hasta 255 caracteres de longitud.

attachments.url : solo se usa si el tipo de datos adjuntos está establecido en file. El URI de la ubicación del archivo. Importante: Este vínculo debe ser accesible públicamente, sin necesidad de autenticación por parte de Exchange Online servidores. Sin embargo, con Exchange local, el vínculo puede ser accesible en una red privada siempre y cuando no necesite autenticación adicional.

attachments.isInline : solo se usa si el tipo de datos adjuntos está establecido en file. Si es true, indica que los datos adjuntos se mostrarán insertados como una imagen en el cuerpo del mensaje y no se mostrarán en la lista de datos adjuntos.

attachments.itemId : solo se usa si el tipo de datos adjuntos está establecido en item. El identificador de elemento de EWS del correo electrónico existente que desea adjuntar al nuevo mensaje. Se trata de una cadena de hasta 100 caracteres.

Devoluciones

void

Comentarios

[ Conjunto de API: Buzón 1.6 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

Office.context.mailbox.displayNewMessageForm({
  toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
  ccRecipients: ["sam@contoso.com"],
  subject: "Outlook add-ins are cool!",
  htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
  attachments: [
    {
      type: "file",
      name: "image.png",
      url: "https://i.imgur.com/9S36xvA.jpg",
      isInline: true
    }
  ]
});

displayNewMessageFormAsync(parameters, options, callback)

Muestra un formulario para crear un mensaje.

El displayNewMessageFormAsync método abre un formulario que permite al usuario crear un nuevo mensaje. Si se especifican parámetros, los campos del formulario del mensaje se rellenan automáticamente con el contenido de los parámetros.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

displayNewMessageFormAsync(parameters: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

parameters: any

Diccionario que contiene todos los valores que se van a rellenar para el usuario en el nuevo formulario. Todos los parámetros son opcionales.

subject : cadena que contiene el asunto del mensaje. La cadena está limitada a un máximo de 255 caracteres.

htmlBody : el cuerpo HTML del mensaje. El contenido del cuerpo está limitado a un tamaño máximo de 32 KB.

attachments : matriz de objetos JSON que son datos adjuntos de archivos o elementos.

attachments.type : indica el tipo de datos adjuntos. Debe ser file para un archivo adjunto o item para un elemento adjunto.

attachments.name : cadena que contiene el nombre de los datos adjuntos, de hasta 255 caracteres de longitud.

options: Office.AsyncContextOptions

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto .

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new message form has been created.
Office.context.mailbox.displayNewMessageFormAsync(
  {
    toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
    ccRecipients: ["sam@contoso.com"],
    subject: "Outlook add-ins are cool!",
    htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
    attachments: [
      {
        type: "file",
        name: "image.png",
        url: "https://i.imgur.com/9S36xvA.jpg",
        isInline: true
      }
    ]
  },
  (asyncResult) => {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewMessageFormAsync(parameters, callback)

Muestra un formulario para crear un mensaje.

Si cualquiera de los parámetros supera los límites de tamaño especificados o si se especifica un nombre de parámetro desconocido, se genera una excepción.

displayNewMessageFormAsync(parameters: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

parameters: any

Diccionario que contiene todos los valores que se van a rellenar para el usuario en el nuevo formulario. Todos los parámetros son opcionales.

subject : cadena que contiene el asunto del mensaje. La cadena está limitada a un máximo de 255 caracteres.

htmlBody : el cuerpo HTML del mensaje. El contenido del cuerpo está limitado a un tamaño máximo de 32 KB.

attachments : matriz de objetos JSON que son datos adjuntos de archivos o elementos.

attachments.type : indica el tipo de datos adjuntos. Debe ser file para un archivo adjunto o item para un elemento adjunto.

attachments.name : cadena que contiene el nombre de los datos adjuntos, de hasta 255 caracteres de longitud.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto .

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Lectura

getCallbackTokenAsync(options, callback)

Obtiene una cadena que contiene un token que se usa para llamar a las API REST o a Exchange Web Services (EWS).

El método getCallbackTokenAsync realiza una llamada asincrónica para obtener un token opaco desde Exchange Server que hospeda el buzón del usuario. La duración del token de devolución de llamada es de 5 minutos.

El token se devuelve como una cadena en la asyncResult.value propiedad .

getCallbackTokenAsync(options: Office.AsyncContextOptions & { isRest?: boolean }, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parámetros

options: Office.AsyncContextOptions & { isRest?: boolean }

Literal de objeto que contiene una o varias de las siguientes propiedades:- isRest: determina si el token proporcionado se usará para las API REST de Outlook o los servicios web de Exchange. El valor predeterminado es false. asyncContext : los datos de estado que se pasan al método asincrónico.

callback: (asyncResult: Office.AsyncResult<string>) => void

Cuando se completa el método, se llama a la función pasada en el parámetro de devolución de llamada con un único parámetro de tipo Office.AsyncResult. El token se devuelve como una cadena en la asyncResult.value propiedad . Si se produjo un error, las propiedades asyncResult.error y asyncResult.diagnostics pueden proporcionar información adicional.

Devoluciones

void

Comentarios

[ Conjunto de API: todos admiten el modo de lectura; Buzón 1.3 introducido Compose compatibilidad con el modo ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

En octubre de 2024, los tokens heredados de identidad de usuario y devolución de llamada de Exchange se desactivarán de forma predeterminada para todos los inquilinos de Exchange Online. Esto forma parte de la Iniciativa de futuro seguro de Microsoft, que proporciona a las organizaciones las herramientas necesarias para responder al panorama actual de amenazas. Los tokens de identidad de usuario de Exchange seguirán funcionando para Exchange local. La autenticación de aplicaciones anidadas es el enfoque recomendado para los tokens en el futuro. Para obtener más información, consulte nuestra entrada de blog y página de preguntas más frecuentes.
Los puntos de conexión REST v2.0 y beta de Outlook ahora están en desuso. Sin embargo, los complementos hospedados en AppSource y de publicación privada pueden usar el servicio REST hasta que finalice el soporte extendido para Outlook 2019 el 14 de octubre de 2025. El tráfico de estos complementos se identifica automáticamente para la exención. Esta exención también se aplica a los nuevos complementos desarrollados a partir del 31 de marzo de 2024. Aunque los complementos pueden usar el servicio REST hasta 2025, le recomendamos encarecidamente que migre los complementos para usar Microsoft Graph. Para obtener instrucciones, consulte Comparación de puntos de conexión de LA API REST de Microsoft Graph y Outlook.
Este método no se admite si carga un complemento en un buzón de correo de Outlook.com o Gmail.
Este método solo se admite en modo de lectura en Outlook en Android y en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.
Las operaciones de EWS no se admiten en complementos que se ejecutan en Outlook en iOS y en Android. Siempre se devuelve un token REST en los clientes móviles de Outlook, incluso si options.isRest está establecido en false.
Llamar al getCallbackTokenAsync método en modo de lectura requiere un nivel de permiso mínimo de elemento de lectura.
Llamar al getCallbackTokenAsync método en modo de redacción requiere que haya guardado el elemento. El saveAsync método requiere un nivel de permiso mínimo de elemento de lectura y escritura.
Para obtener instrucciones sobre escenarios de delegación o compartidos, consulte el artículo carpetas compartidas y buzón compartido .

Tokens de REST

Cuando se solicita un token REST (options.isRest = true), el token resultante no funcionará para autenticar las llamadas de EWS. El token se limitará en el ámbito al acceso de solo lectura al elemento actual y sus datos adjuntos, a menos que el complemento haya especificado el permiso de buzón de lectura y escritura en su manifiesto. Si se especifica el permiso de buzón de lectura y escritura , el token resultante concederá acceso de lectura y escritura al correo, el calendario y los contactos, incluida la capacidad de enviar correo.

El complemento debe usar la propiedad restUrl para determinar la URL correcta que se va a usar al realizar las llamadas a la API de REST.

Esta API funciona para los siguientes ámbitos.

Mail.ReadWrite
Mail.Send
Calendars.ReadWrite
Contacts.ReadWrite

Tokens EWS

Cuando se solicita un token de EWS (options.isRest = false), el token resultante no funcionará para autenticar las llamadas a la API REST. El token estará limitado en su ámbito para el acceso al elemento actual.

El complemento debe usar la propiedad ewsUrl para determinar la URL correcta que se va a usar al realizar las llamadas a EWS.

Puede pasar el token y un identificador de datos adjuntos o un identificador de elemento a un sistema externo. Ese sistema usa el token como token de autorización de portador para llamar a la operación GetAttachment de Servicios web de Exchange (EWS) o a la operación GetItem para devolver datos adjuntos o elementos. Por ejemplo, puede crear un servicio remoto para obtener datos adjuntos del elemento seleccionado.

Errores:

HTTPRequestFailure : se ha producido un error en la solicitud. Compruebe el objeto de diagnóstico para ver el código de error HTTP.
InternalServerError : el servidor Exchange devolvió un error. Compruebe el objeto de diagnóstico para obtener más información.
NetworkError : el usuario ya no está conectado a la red. Compruebe la conexión de red y vuelva a intentarlo.

getCallbackTokenAsync(callback, userContext)

Obtiene una cadena que contiene un token usado para obtener datos adjuntos o un elemento de Exchange Server.

El token se devuelve como una cadena en la asyncResult.value propiedad .

getCallbackTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parámetros

callback: (asyncResult: Office.AsyncResult<string>) => void

userContext: any

Opcional. Cualquier dato de estado que se pasa al método asincrónico.

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

En octubre de 2024, los tokens heredados de identidad de usuario y devolución de llamada de Exchange se desactivarán de forma predeterminada para todos los inquilinos de Exchange Online. Esto forma parte de la Iniciativa de futuro seguro de Microsoft, que proporciona a las organizaciones las herramientas necesarias para responder al panorama actual de amenazas. Los tokens de identidad de usuario de Exchange seguirán funcionando para Exchange local. La autenticación de aplicaciones anidadas es el enfoque recomendado para los tokens en el futuro. Para obtener más información, consulte nuestra entrada de blog y página de preguntas más frecuentes.
Puede pasar el token y un identificador de datos adjuntos o un identificador de elemento a un sistema externo. Ese sistema usa el token como token de autorización de portador para llamar a la operación GetAttachment o GetItem de Exchange Web Services (EWS) para devolver datos adjuntos o elementos. Por ejemplo, puede crear un servicio remoto para obtener datos adjuntos del elemento seleccionado.
Llamar al getCallbackTokenAsync método en modo de lectura requiere un nivel de permiso mínimo de elemento de lectura.
Llamar al getCallbackTokenAsync método en modo de redacción requiere que haya guardado el elemento. El saveAsync método requiere un nivel de permiso mínimo de elemento de lectura y escritura.
Este método no se admite en Outlook en Android o en iOS. Las operaciones de EWS no se admiten en complementos que se ejecutan en Outlook en clientes móviles. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.
Este método no se admite si carga un complemento en un buzón de correo de Outlook.com o Gmail.
Para obtener instrucciones sobre escenarios de delegación o compartidos, consulte el artículo carpetas compartidas y buzón compartido .

Errores:

HTTPRequestFailure : se ha producido un error en la solicitud. Compruebe el objeto de diagnóstico para ver el código de error HTTP.
InternalServerError : el servidor Exchange devolvió un error. Compruebe el objeto de diagnóstico para obtener más información.
NetworkError : el usuario ya no está conectado a la red. Compruebe la conexión de red y vuelva a intentarlo.

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-callback-token.yaml

Office.context.mailbox.getCallbackTokenAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
        return;
    }

    console.log(result.value);
});

getSelectedItemsAsync(options, callback)

Obtiene los mensajes seleccionados actualmente en los que un complemento puede activar y realizar operaciones. Un complemento puede activarse en un máximo de 100 mensajes a la vez. Para obtener más información sobre la selección múltiple de elementos, vea Activar el complemento de Outlook en varios mensajes.

getSelectedItemsAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Parámetros

options: Office.AsyncContextOptions

callback: (asyncResult: Office.AsyncResult<Office.SelectedItemDetails[]>) => void

Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto . Las propiedades de los mensajes seleccionados, como el identificador de elemento y el asunto, se devuelven como una matriz de objetos SelectedItemDetails en la asyncResult.value propiedad . Los objetos de la matriz siguen el orden en que se seleccionaron los mensajes.

Devoluciones

void

Comentarios

[ Conjunto de API: Buzón 1.13 ]

Nivel mínimo de permiso: buzón de lectura y escritura

Modo de Outlook aplicable: Compose, Lectura

Importante: Este método solo se aplica a los mensajes.

getSelectedItemsAsync(callback)

getSelectedItemsAsync(callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Parámetros

callback: (asyncResult: Office.AsyncResult<Office.SelectedItemDetails[]>) => void

Devoluciones

void

Comentarios

[ Conjunto de API: Buzón 1.13 ]

Nivel mínimo de permiso: buzón de lectura y escritura

Modo de Outlook aplicable: Compose, Lectura

Importante: Este método solo se aplica a los mensajes.

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-message-properties.yaml

// Retrieves the selected messages' properties and logs them to the console.
Office.context.mailbox.getSelectedItemsAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  asyncResult.value.forEach((message) => {
    console.log(`Item ID: ${message.itemId}`);
    console.log(`Conversation ID: ${message.conversationId}`);
    console.log(`Internet message ID: ${message.internetMessageId}`);
    console.log(`Subject: ${message.subject}`);
    console.log(`Item type: ${message.itemType}`);
    console.log(`Item mode: ${message.itemMode}`);
    console.log(`Has attachment: ${message.hasAttachment}`);
  });
});

getUserIdentityTokenAsync(callback, userContext)

Obtiene un token que identifica al usuario y al complemento de Office.

El token se devuelve como una cadena en la asyncResult.value propiedad .

getUserIdentityTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parámetros

callback: (asyncResult: Office.AsyncResult<string>) => void

userContext: any

Opcional. Cualquier dato de estado que se pasa al método asincrónico.

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Importante:

En octubre de 2024, los tokens heredados de identidad de usuario y devolución de llamada de Exchange se desactivarán de forma predeterminada para todos los inquilinos de Exchange Online. Esto forma parte de la Iniciativa de futuro seguro de Microsoft, que proporciona a las organizaciones las herramientas necesarias para responder al panorama actual de amenazas. Los tokens de identidad de usuario de Exchange seguirán funcionando para Exchange local. La autenticación de aplicaciones anidadas es el enfoque recomendado para los tokens en el futuro. Para obtener más información, consulte nuestra entrada de blog y página de preguntas más frecuentes.
El getUserIdentityTokenAsync método devuelve un token que puede usar para identificar y autenticar el complemento y el usuario con un sistema externo.
Este método no se admite si carga un complemento en un buzón de correo de Outlook.com o Gmail.

Errores:

HTTPRequestFailure : se ha producido un error en la solicitud. Compruebe el objeto de diagnóstico para ver el código de error HTTP.
InternalServerError : el servidor Exchange devolvió un error. Compruebe el objeto de diagnóstico para obtener más información.
NetworkError : el usuario ya no está conectado a la red. Compruebe la conexión de red y vuelva a intentarlo.

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-identity-token.yaml

Office.context.mailbox.getUserIdentityTokenAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`)
        return;
    }

    console.log(result.value);
});

makeEwsRequestAsync(data, callback, userContext)

Realiza una solicitud asincrónica a un servicio de Exchange Web Services (EWS) en el servidor exchange que hospeda el buzón del usuario.

El método makeEwsRequestAsync envía una solicitud de EWS en nombre del complemento a Exchange.

makeEwsRequestAsync(data: any, callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parámetros

data: any

La solicitud de EWS.

callback: (asyncResult: Office.AsyncResult<string>) => void

Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro, asyncResult, que es un Office.AsyncResult objeto . La respuesta XML de la solicitud EWS se proporciona como una cadena en la asyncResult.value propiedad . En Outlook en la Web, en Windows (nuevo y clásico (a partir de la versión 2303, compilación 16225.10000)) y en Mac (a partir de la versión 16.73 (23042601)), si la respuesta supera los 5 MB de tamaño, se devuelve un mensaje de error en la asyncResult.error propiedad . En versiones anteriores de Outlook en Windows (clásico) y en Mac, se devuelve un mensaje de error si la respuesta supera el tamaño de 1 MB.

userContext: any

Opcional. Cualquier dato de estado que se pasa al método asincrónico.

Devoluciones

void

Comentarios

Nivel mínimo de permiso: buzón de lectura y escritura

Modo de Outlook aplicable: Compose o lectura

Importante:

En octubre de 2024, los tokens heredados de identidad de usuario y devolución de llamada de Exchange se desactivarán de forma predeterminada para todos los inquilinos de Exchange Online. Esto forma parte de la Iniciativa de futuro seguro de Microsoft, que proporciona a las organizaciones las herramientas necesarias para responder al panorama actual de amenazas. Los tokens de identidad de usuario de Exchange seguirán funcionando para Exchange local. La autenticación de aplicaciones anidadas es el enfoque recomendado para los tokens en el futuro. Para obtener más información, consulte nuestra entrada de blog y página de preguntas más frecuentes.
Para habilitar el makeEwsRequestAsync método para realizar solicitudes de EWS, el administrador del servidor debe establecer en OAuthAuthenticationtrue en el directorio EWS del servidor de acceso de cliente .
El complemento debe tener el permiso de buzón de lectura y escritura para usar el makeEwsRequestAsync método . Para obtener información sobre cómo usar el permiso de buzón de lectura y escritura y las operaciones de EWS a las que puede llamar con el makeEwsRequestAsync método , vea Especificar permisos para el acceso del complemento de correo al buzón del usuario.
Si el complemento necesita tener acceso a elementos asociados a la carpeta o su solicitud XML debe especificar la codificación UTF-8 (\<?xml version="1.0" encoding="utf-8"?\>), debe usar Microsoft Graph o las API REST para acceder al buzón del usuario en su lugar.
Este método no se admite en Outlook en Android o en iOS. Para obtener más información sobre las API admitidas en Outlook mobile, vea API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.
Este método no se admite cuando el complemento se carga en un buzón de Gmail.
Cuando se usa el makeEwsRequestAsync método en complementos que se ejecutan en versiones de Outlook anteriores a la versión 15.0.4535.1004, debe establecer el valor de codificación en ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>). Para determinar la versión de un cliente de Outlook, use la mailbox.diagnostics.hostVersion propiedad . No es necesario establecer el valor de codificación cuando el complemento se ejecuta en Outlook en la Web y nueva Outlook en Windows. Para determinar el cliente de Outlook en el que se ejecuta el complemento, use la mailbox.diagnostics.hostName propiedad .

Ejemplos

function getSubjectRequest(id) {
    // Return a GetItem operation request for the subject of the specified item.
    const request =
        '<?xml version="1.0" encoding="utf-8"?>' +
        '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
        '               xmlns:xsd="http://www.w3.org/2001/XMLSchema"' +
        '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
        '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
        '  <soap:Header>' +
        '    <RequestServerVersion Version="Exchange2016" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
        '  </soap:Header>' +
        '  <soap:Body>' +
        '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
        '      <ItemShape>' +
        '        <t:BaseShape>IdOnly</t:BaseShape>' +
        '        <t:AdditionalProperties>' +
        '            <t:FieldURI FieldURI="item:Subject"/>' +
        '        </t:AdditionalProperties>' +
        '      </ItemShape>' +
        '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
        '    </GetItem>' +
        '  </soap:Body>' +
        '</soap:Envelope>';

    return request;
}

function sendRequest() {
    // Create a local variable that contains the mailbox.
    Office.context.mailbox.makeEwsRequestAsync(
        getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
    const result = asyncResult.value;
    const context = asyncResult.asyncContext;

    // Process the returned response here.
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/get-icaluid-as-attendee.yaml

const ewsId = Office.context.mailbox.item.itemId;
const request = `<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><t:RequestServerVersion Version="Exchange2013" /></soap:Header>
      <soap:Body>
        <m:GetItem>
          <m:ItemShape>
            <t:BaseShape>AllProperties</t:BaseShape>
          </m:ItemShape >
          <m:ItemIds>
            <t:ItemId Id="${ewsId}" />
          </m:ItemIds>
        </m:GetItem>
      </soap:Body>
    </soap:Envelope>`;

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(result.error.message);
    return;
  }

  console.log(getUID(result.value));
});

...

const request = '<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><t:RequestServerVersion Version="Exchange2010" /></soap:Header>'+
    '  <soap:Body>'+
    '    <m:CreateItem MessageDisposition="SendAndSaveCopy">'+
    '      <m:SavedItemFolderId><t:DistinguishedFolderId Id="sentitems" /></m:SavedItemFolderId>'+
    '      <m:Items>'+
    '        <t:Message>'+
    '          <t:Subject>Hello, Outlook!</t:Subject>'+
    '          <t:Body BodyType="HTML">This message was sent from a ScriptLab code sample, used from ' + Office.context.mailbox.diagnostics.hostName + ', version ' + Office.context.mailbox.diagnostics.hostVersion + '!</t:Body>'+
    '          <t:ToRecipients>'+
    '            <t:Mailbox><t:EmailAddress>' + Office.context.mailbox.userProfile.emailAddress + '</t:EmailAddress></t:Mailbox>'+
    '          </t:ToRecipients>'+
    '        </t:Message>'+
    '      </m:Items>'+
    '    </m:CreateItem>'+
    '  </soap:Body>'+
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
    console.log(result);
});

removeHandlerAsync(eventType, options, callback)

Elimina el controlador de eventos de un tpo de evento admitido. Nota: Los eventos solo están disponibles con la implementación del panel de tareas.

Para ver los eventos admitidos, consulte la sección Eventos del modelo de objetos de buzón.

removeHandlerAsync(eventType: Office.EventType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

eventType: Office.EventType | string

El evento que debe revocar el controlador.

options: Office.AsyncContextOptions

Proporciona una opción para conservar los datos de contexto de cualquier tipo, sin cambios, para su uso en una devolución de llamada.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro de tipo Office.AsyncResult.

Devoluciones

void

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

removeHandlerAsync(eventType, callback)

Elimina el controlador de eventos de un tpo de evento admitido. Nota: Los eventos solo están disponibles con la implementación del panel de tareas.

Para ver los eventos admitidos, consulte la sección Eventos del modelo de objetos de buzón.

removeHandlerAsync(eventType: Office.EventType | string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parámetros

eventType: Office.EventType | string

El evento que debe revocar el controlador.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro de tipo Office.AsyncResult.

Devoluciones

void

Comentarios