Compartir a través de

Usar las API de REST de Outlook desde un complemento de Outlook

El espacio de nombres Office.context.mailbox.item proporciona acceso a muchos de los campos comunes de mensajes y citas. Sin embargo, en algunos escenarios, es posible que un complemento tenga que acceder a datos que no están expuestos por el espacio de nombres. Por ejemplo, el complemento puede basarse en propiedades personalizadas que establece una aplicación externa, o necesita buscar el buzón del usuario para obtener mensajes del mismo remitente. En estos escenarios, las API de REST de Outlook es el método recomendado para recuperar la información.

Importante

Los puntos de conexión rest de Outlook v2.0 y beta están en desuso

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 todavía 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 octubre de 2025, le recomendamos encarecidamente que migre los complementos para usar Microsoft Graph.

Obtener un token de acceso

Importante

Los tokens de Exchange heredados están en desuso. Los tokens de devolución de llamada e identidad de usuario de Exchange heredados se han desactivado para la mayoría de los inquilinos Exchange Online. Los administradores pueden volver a habilitar tokens heredados para inquilinos y complementos hasta junio de 2025. En octubre de 2025, los tokens heredados se desactivarán completamente para todos los inquilinos. Para ver la escala de tiempo y los detalles, consulte nuestra página de preguntas más frecuentes. 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.

Las API de REST de Outlook necesitan un token de portador en el encabezado Authorization. Normalmente, las aplicaciones usan flujos de OAuth2 para recuperar un token. Sin embargo, los complementos pueden recuperar un token sin implementar OAuth2 mediante el nuevo método Office.context.mailbox.getCallbackTokenAsync introducido en el conjunto de requisitos de buzón 1.5.

Al establecer la opción isRest en true, puede solicitar un token compatible con las API de REST.

Agregar permisos y ámbito del token

Es importante tener en cuenta el nivel de acceso que necesitará el complemento mediante las API de REST. En la mayoría de los casos, el token que se ha devuelto mediante getCallbackTokenAsync, proporcionará acceso de solo lectura únicamente al elemento actual. Esto es cierto incluso si el complemento especifica el nivel de permiso de elemento de lectura y escritura en su manifiesto.

Si el complemento requerirá acceso de escritura al elemento actual u otros elementos del buzón del usuario, el complemento debe especificar el permiso de buzón de lectura y escritura. nivel en su manifiesto. En este caso, el token devuelto contendrá acceso de lectura y escritura a los contactos, eventos y mensajes del usuario.

Ejemplo

Office.context.mailbox.getCallbackTokenAsync({isRest: true}, function(result){
  if (result.status === "succeeded") {
    const accessToken = result.value;

    // Use the access token.
    getCurrentItem(accessToken);
  } else {
    // Handle the error.
  }
});

Obtener el identificador de elemento

Para recuperar el elemento actual mediante REST, el complemento necesitará el identificador del elemento, con un formato adecuado para REST. Este se obtiene de la propiedad Office.context.mailbox.item.itemId, pero deben realizarse algunas comprobaciones para asegurarse de que se trata de un identificador con formato para REST.

  • En Outlook en dispositivos móviles, el valor devuelto por Office.context.mailbox.item.itemId es un identificador con formato REST y se puede usar tal cual.
  • En otros clientes de Outlook, el valor devuelto por Office.context.mailbox.item.itemId es un id. con formato para EWS y tiene que convertirse con el método Office.context.mailbox.convertToRestId.
  • Tenga en cuenta que debe convertir también el ID de datos adjuntos a un ID con formato REST para usarlo. El motivo por el que se deben convertir los id. es que los ID de EWS pueden contener valores seguros sin direcciones URL que provocarán problemas para REST.

El complemento puede determinar qué cliente de Outlook está cargado al comprobar la propiedad Office.context.mailbox.diagnostics.hostName.

Ejemplo

function getItemRestId() {
  if (Office.context.mailbox.diagnostics.hostName === 'OutlookIOS') {
    // itemId is already REST-formatted.
    return Office.context.mailbox.item.itemId;
  } else {
    // Convert to an item ID for API v2.0.
    return Office.context.mailbox.convertToRestId(
      Office.context.mailbox.item.itemId,
      Office.MailboxEnums.RestVersion.v2_0
    );
  }
}

Obtener la dirección URL de la API de REST

La última información que el complemento necesita para llamar a la API de REST es el nombre de host que debe usar para enviar solicitudes de API. Esta información se encuentra en la propiedad Office.context.mailbox.restUrl.

Ejemplo

// Example: https://outlook.office.com
const restHost = Office.context.mailbox.restUrl;

Llamar a la API

Cuando el complemento tenga el token de acceso, el identificador del elemento y la dirección URL de la API de REST, podrá pasar esa información a un servicio de back-end que llame a la API de REST o llamarla directamente con AJAX. En el ejemplo siguiente se llama a la API de REST de Correo de Outlook para obtener el mensaje actual.

Importante

En el caso de las implementaciones de Exchange locales, se produce un error en las solicitudes del lado cliente que usan AJAX o bibliotecas similares porque CORS no se admite en esa configuración del servidor.

function getCurrentItem(accessToken) {
  // Get the item's REST ID.
  const itemId = getItemRestId();

  // Construct the REST URL to the current item.
  // Details for formatting the URL can be found at
  // https://learn.microsoft.com/previous-versions/office/office-365-api/api/version-2.0/mail-rest-operations#get-messages.
  const getMessageUrl = Office.context.mailbox.restUrl +
    '/v2.0/me/messages/' + itemId;

  $.ajax({
    url: getMessageUrl,
    dataType: 'json',
    headers: { 'Authorization': 'Bearer ' + accessToken }
  }).done(function(item){
    // Message is passed in `item`.
    const subject = item.Subject;
    ...
  }).fail(function(error){
    // Handle error.
  });
}

Vea también