Compartir a través de


Office.Mailbox interface

Proporciona acceso al modelo de objetos del complemento de Microsoft Outlook.

Propiedades clave:

  • diagnostics : proporciona información de diagnóstico a un complemento de Outlook.

  • item : proporciona métodos y propiedades para acceder a un mensaje o una cita en un complemento de Outlook.

  • userProfile : proporciona información sobre el usuario en un complemento de Outlook.

Comentarios

Nivel mínimo de permiso: restringido

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

Propiedades

diagnostics

Proporciona información de diagnóstico a un complemento de Outlook.

Contiene los siguientes miembros.

  • hostName (cadena): cadena que representa el nombre de la aplicación de Office. Debe ser uno de los siguientes valores: Outlook,newOutlookWindows , OutlookWebApp, OutlookIOSo .OutlookAndroid Nota: El valor "Outlook" se devuelve para Outlook en Windows (clásico) y en Mac.

  • hostVersion(cadena): cadena que representa la versión de la aplicación de Office o la Exchange Server (por ejemplo, "15.0.468.0"). Si el complemento de correo se ejecuta en Outlook en Windows (clásico), en Mac o en dispositivos móviles, la hostVersion propiedad devuelve la versión del cliente de Outlook. En Outlook en la Web y nueva Outlook en Windows, la propiedad devuelve la versión del Exchange Server.

  • OWAView(MailboxEnums.OWAView o cadena): enumeración (o literal de cadena) que representa la vista actual de Outlook en la Web. Si la aplicación no está Outlook en la Web, el acceso a esta propiedad da como resultado undefined. Outlook en la Web tiene tres vistas ( -OneColumn mostradas cuando la pantalla es estrecha, TwoColumns - mostradas cuando la pantalla es más ancha y ThreeColumns - mostradas cuando la pantalla es ancha) que corresponden al ancho de la pantalla y a la ventana, y el número de columnas que se pueden mostrar.

Más información en Office.Diagnostics.

ewsUrl

Obtiene la dirección URL del punto de conexión de Servicios Web Exchange (EWS) para esta cuenta de correo electrónico.

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:

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Importante:

restUrl

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

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

Métodos

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

convertToEwsId(id, restVersion)

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

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.

convertToRestId(id, restVersion)

Convierte un identificador admitido en formato REST.

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.

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.

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.

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.

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(callback, userContext)

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

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 .

getIsIdentityManaged()

Devuelve true si Microsoft Intune administra el buzón actual.

getIsOpenFromLocationAllowed(openLocation)

Devuelve true si la directiva de administración de aplicaciones móviles (MAM) Intune de una organización permite a un complemento acceder a los datos desde la ubicación especificada.

getIsSaveToLocationAllowed(saveLocation)

Devuelve true si la directiva de administración de aplicaciones móviles (MAM) Intune de una organización permite a un complemento guardar datos en la ubicación especificada.

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 .

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.

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

Detalles de las propiedades

diagnostics

Proporciona información de diagnóstico a un complemento de Outlook.

Contiene los siguientes miembros.

  • hostName (cadena): cadena que representa el nombre de la aplicación de Office. Debe ser uno de los siguientes valores: Outlook,newOutlookWindows , OutlookWebApp, OutlookIOSo .OutlookAndroid Nota: El valor "Outlook" se devuelve para Outlook en Windows (clásico) y en Mac.

  • hostVersion(cadena): cadena que representa la versión de la aplicación de Office o la Exchange Server (por ejemplo, "15.0.468.0"). Si el complemento de correo se ejecuta en Outlook en Windows (clásico), en Mac o en dispositivos móviles, la hostVersion propiedad devuelve la versión del cliente de Outlook. En Outlook en la Web y nueva Outlook en Windows, la propiedad devuelve la versión del Exchange Server.

  • OWAView(MailboxEnums.OWAView o cadena): enumeración (o literal de cadena) que representa la vista actual de Outlook en la Web. Si la aplicación no está Outlook en la Web, el acceso a esta propiedad da como resultado undefined. Outlook en la Web tiene tres vistas ( -OneColumn mostradas cuando la pantalla es estrecha, TwoColumns - mostradas cuando la pantalla es más ancha y ThreeColumns - mostradas cuando la pantalla es ancha) que corresponden al ancho de la pantalla y a la ventana, y el número de columnas que se pueden mostrar.

Más información en Office.Diagnostics.

diagnostics: Diagnostics;

Valor de propiedad

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

A partir del conjunto de requisitos de buzón 1.5, también puede usar la propiedad Office.context.diagnostics para obtener información similar.

Ejemplos

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

// This function gets a mailbox's diagnostic information, such as Outlook client and version, and logs it to the console.
const diagnostics = Office.context.mailbox.diagnostics;
console.log(`Client application: ${diagnostics.hostName}`);
console.log(`Client version: ${diagnostics.hostVersion}`);

switch (diagnostics.OWAView) {
  case undefined:
    console.log("Current view (Outlook on the web only): Not applicable. An Outlook desktop client is in use.");
    break;
  case Office.MailboxEnums.OWAView.OneColumnNarrow:
    console.log("Current view (Outlook on the web only): Viewed from an older generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.OneColumn:
    console.log("Current view (Outlook on the web only): Viewed from a newer generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.TwoColumns:
    console.log("Current view (Outlook on the web only): Viewed from a tablet");
    break;
  case Office.MailboxEnums.OWAView.ThreeColumns:
    console.log("Current view (Outlook on the web only): Viewed from a desktop computer");
    break;
}

ewsUrl

Obtiene la dirección URL del punto de conexión de Servicios Web Exchange (EWS) para esta cuenta de correo electrónico.

ewsUrl: string;

Valor de propiedad

string

Comentarios

[ Conjunto de API: Buzón 1.1 ]

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:

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Importante:

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

Valor de propiedad

restUrl

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

restUrl: string;

Valor de propiedad

string

Comentarios

[ Conjunto de API: Buzón 1.5 ]

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

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

[ Conjunto de API: Buzón 1.5 ]

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

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.

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

[ Conjunto de API: Buzón 1.5 ]

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

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

[ Conjunto de API: Buzón 1.1 ]

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

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

[ Conjunto de API: Buzón 1.1 ]

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

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

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: 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-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!"
});

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: Buzón 1.5 ]

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 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(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parámetros

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.

userContext

any

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

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.

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

getIsIdentityManaged()

Devuelve true si Microsoft Intune administra el buzón actual.

getIsIdentityManaged(): boolean;

Devoluciones

boolean

True si Microsoft Intune administra el buzón actual.

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose, Lectura

Importante: Este método solo se admite en Outlook en Android y en iOS a partir de la versión 4.2443.0.To más información sobre las API admitidas en Outlook en dispositivos móviles, consulte Api de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Errores:

  • MAMServiceNotAvailable : el cliente no puede capturar la directiva de administración de aplicaciones móviles (MAM).

getIsOpenFromLocationAllowed(openLocation)

Devuelve true si la directiva de administración de aplicaciones móviles (MAM) Intune de una organización permite a un complemento acceder a los datos desde la ubicación especificada.

getIsOpenFromLocationAllowed(openLocation: MailboxEnums.OpenLocation): boolean;

Parámetros

openLocation
Office.MailboxEnums.OpenLocation

Ubicación desde la que el complemento intenta acceder a los datos.

Devoluciones

boolean

True si la directiva mam de Intune de una organización permite a un complemento acceder a los datos desde la ubicación especificada.

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose, Lectura

Importante: Este método solo se admite en Outlook en Android y en iOS a partir de la versión 4.2443.0. Para obtener más información sobre las API admitidas en Outlook en dispositivos móviles, consulte API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Errores:

  • InvalidOpenLocationInput : el valor de la ubicación especificada no es válido.

  • MAMServiceNotAvailable : el cliente no puede capturar la directiva MAM.

getIsSaveToLocationAllowed(saveLocation)

Devuelve true si la directiva de administración de aplicaciones móviles (MAM) Intune de una organización permite a un complemento guardar datos en la ubicación especificada.

getIsSaveToLocationAllowed(saveLocation: MailboxEnums.SaveLocation): boolean;

Parámetros

saveLocation
Office.MailboxEnums.SaveLocation

Ubicación en la que el complemento intenta guardar datos.

Devoluciones

boolean

True si la directiva mam de Intune de una organización permite a un complemento guardar datos en la ubicación especificada.

Comentarios

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose, Lectura

Importante: Este método solo se admite en Outlook en Android y en iOS a partir de la versión 4.2443.0. Para obtener más información sobre las API admitidas en Outlook en dispositivos móviles, consulte API de JavaScript de Outlook compatibles con Outlook en dispositivos móviles.

Errores:

  • InvalidSaveLocationInput : el valor de la ubicación especificada no es válido.

  • MAMServiceNotAvailable : el cliente no puede capturar la directiva MAM.

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

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.

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

[ Conjunto de API: Buzón 1.1 ]

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 o nuevo 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

[ Conjunto de API: Buzón 1.5 ]

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

[ Conjunto de API: Buzón 1.5 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Compose o lectura

Ejemplos

Office.context.mailbox.removeHandlerAsync(Office.EventType.OfficeThemeChanged, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error("Failed to remove event handler: " + asyncResult.error.message);
        return;
    }

    console.log("Event handler removed successfully.");
});